> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/api/mcp/tools.md). # Tools Reference The Blotato MCP Server exposes 26 tools. Your AI tool calls these automatically based on your prompts. ## Accounts ### blotato\_get\_user Get your account info and verify the connection is working. * **Input**: none * **Output**: user ID, email, subscription status ### blotato\_list\_accounts List all connected social media accounts with subaccounts (for Facebook Pages and LinkedIn Company Pages). * **Input**: `platform` (optional) - filter by platform name * **Output**: array of accounts with ID, platform, name, username, and subaccounts ### blotato\_list\_pinterest\_boards List boards owned by a connected Pinterest account. Use this to get the `boardId` required when publishing a Pinterest pin. * **Input**: `accountId` (required) - Pinterest account ID from blotato\_list\_accounts * **Output**: array of boards with `id` and `name`. Use `id` as `boardId` in blotato\_create\_post. *** ## Publishing ### blotato\_create\_post Create and publish (or schedule) a post to a social media platform. * **Input**: * `accountId` (required) - from blotato\_list\_accounts * `platform` (required) - twitter, instagram, facebook, tiktok, linkedin, pinterest, bluesky, threads, or youtube * `text` (required) - post content * `mediaUrls` (optional) - array of public media URLs * `scheduledTime` (optional) - ISO 8601 datetime * `useNextFreeSlot` (optional) - use next available schedule slot * `pageId` (optional) - for Facebook/LinkedIn pages * `mediaType` (optional) - for Instagram/Facebook: reel or story. Facebook videos must be `"reel"` (regular feed videos no longer supported). * `trial` (optional) - for Instagram reels: object with `graduationStrategy` (`"MANUAL"` or `"SS_PERFORMANCE"`). Trial reels are shown to non-followers first. * `privacyLevel` (optional) - for TikTok * `additionalPosts` (optional) - array of additional posts for threads (Twitter, Bluesky, Threads). Each entry has `text` and `mediaUrls`. The first post uses the top-level `text` and `mediaUrls` fields. Blotato handles reply chaining. * `boardId` (optional) - for Pinterest (get from blotato\_list\_pinterest\_boards) * `title` (optional) - for Pinterest or YouTube * `privacyStatus` (optional) - for YouTube: public, private, or unlisted * `playlistIds` (optional) - for YouTube: array of playlist IDs from blotato\_list\_subaccounts to add the video to playlists * `thumbnailUrl` (optional) - for YouTube: publicly accessible image URL for a custom thumbnail. Requires a verified YouTube account in good standing * **Output**: postSubmissionId (poll with blotato\_get\_post\_status) ### blotato\_get\_post\_status Check the status of a submitted post. * **Input**: `postSubmissionId` (required) * **Output**: status, publicUrl (when published), errorMessage (when failed) * **Status values**: in-progress -> published | scheduled | failed ### blotato\_list\_posts List the user's posts (scheduled, published, and failed) within a time window, ordered by post time (most recent first). Supports cursor-based pagination and optional filters by status and platform. Each item includes a `state` field with a `type` of `scheduled`, `published` (includes `postUrl`), or `failed` (includes `errorMessage`). * **Input**: * `since` (optional) - ISO 8601 timestamp. Defaults to 7 days ago. * `until` (optional) - ISO 8601 timestamp. Defaults to 7 days from now. * `limit` (optional) - number of posts per page. Min: 1, Max: 250. Default: 50 * `cursor` (optional) - pagination cursor from a previous response * `status` (optional) - array of statuses to include: `scheduled`, `published`, `failed`. Omit to include all. * `platform` (optional) - array of platforms to include: twitter, instagram, linkedin, facebook, tiktok, pinterest, threads, bluesky, youtube. Omit to include all. * **Output**: array of posts with `id`, `postTime`, `platform`, `text`, `mediaUrls`, and a `state` object. Includes `cursor` for the next page when more pages are available. *** ## Analytics ### blotato\_list\_top\_posts List your top performing published posts, ranked by an engagement metric over a time range. Use this to answer questions like "what were my best posts last month" or "which posts got the most views". Each item includes the post content, public URL, platform, publish time, media URLs, the latest analytics snapshot, and the full snapshot history. Analytics are refreshed periodically in the background, so recent posts may have no metrics yet. Metric values are returned as strings because counts can exceed normal number precision. * **Input**: * `since` (optional) - ISO 8601 timestamp. Only include posts published on or after this time. Defaults to 30 days ago. * `until` (optional) - ISO 8601 timestamp. Only include posts published on or before this time. Defaults to now. * `platform` (optional) - filter to a single platform: twitter, instagram, facebook, threads, or bluesky. Omit to include all. Analytics for other platforms are not collected yet. * `sortBy` (optional) - metric to rank by: `likes_count`, `comments_count`, `views_count`, or `reach_count`. Defaults to `views_count`. * `limit` (optional) - number of posts to return. Min: 1, Max: 100. Default: 20 * **Output**: array of `items`, each with `id`, `content`, `postUrl`, `platform`, `createdAt`, `mediaUrls`, `latestMetrics`, and `metricsHistory`. ### blotato\_get\_post\_analytics Get analytics for a single published post, including the latest metrics and the full snapshot history. This does not trigger a re-fetch; it returns the most recent analytics collected in the background. Use blotato\_list\_posts or blotato\_list\_top\_posts to find the published post id first. * **Input**: `id` (required) - published post id from blotato\_list\_posts or blotato\_list\_top\_posts * **Output**: `publishedPostId`, `platform`, `lastFetchedAt`, `lastError`, `metrics` (latest, or null when not synced yet), and `history` (array of snapshots, each with `fetchedAt` and `metrics`). ## Comments Read and post comments on your published Instagram posts, both audience replies and comments you post through Blotato. ### blotato\_list\_comments List comments on your published posts, ordered by creation time (most recent first). Supports cursor-based pagination and optional filters. Each comment includes an `isAuthor` flag: `true` for comments you posted, `false` for audience replies. * **Input**: * `limit` (optional) - number of comments per page. Min: 1, Max: 250. Default: 50 * `cursor` (optional) - pagination cursor from a previous response * `platform` (optional) - filter by platform: `instagram` * `accountId` (optional) - filter to a single connected account * `parentCommentId` (optional) - filter to direct replies to a single comment * `postId` (optional) - filter to comments on a single Blotato-published post (from blotato\_list\_posts) * `since` (optional) - only include comments created on or after this ISO 8601 timestamp * `until` (optional) - only include comments created on or before this ISO 8601 timestamp * **Output**: array of comments with `id`, `text`, `status`, `isAuthor`, `platform`, `postId`, `parentCommentId`, `createdAt`, and `errorMessage` (when failed). Includes `cursor` for the next page when present. ### blotato\_get\_comment Get a single comment by its Blotato ID. * **Input**: `commentId` (required) - comment ID from blotato\_list\_comments * **Output**: `id`, `text`, `status`, `isAuthor`, `platform`, `postId`, `createdAt`, and `errorMessage` (when failed) ### blotato\_post\_comment Post a comment on one of your published Instagram posts, or a reply to an existing top-level comment when you pass `parentCommentId`. Blotato queues the comment and posts it in the background. To check the status of the comment, poll with blotato\_get\_comment. Replies to audience comments count toward your plan's monthly active-contacts limit. * **Input**: * `postId` (required) - Blotato ID of the published post (from blotato\_list\_posts) * `text` (required) - comment body. Instagram allows up to 2200 characters * `parentCommentId` (optional) - Blotato ID of a top-level, posted comment on the same post to reply to. Replies to replies are not supported * **Output**: the queued comment (poll with blotato\_get\_comment) * **Status values**: queued -> processing -> posted | failed *** ## Messages Read and send direct messages on your Instagram account. Reply to people who already have a conversation with you. ### blotato\_list\_conversations List your direct-message conversations, ordered by most recent activity. Supports cursor-based pagination and optional filters. * **Input**: * `limit` (optional) - number of conversations per page. Min: 1, Max: 250. Default: 50 * `cursor` (optional) - pagination cursor from a previous response * `platform` (optional) - filter by platform: `instagram` * `accountId` (optional) - filter to a single connected account * **Output**: array of conversations with `id`, `platform`, `participants`, `updatedAt`, and `createdAt`. Includes `cursor` for the next page when present. ### blotato\_get\_conversation Get a single conversation by its Blotato ID. * **Input**: `conversationId` (required) - conversation ID from blotato\_list\_conversations * **Output**: conversation object with `id`, `platform`, `participants`, and `updatedAt` ### blotato\_list\_messages List your messages, ordered by creation time (most recent first). Supports cursor-based pagination and optional filters. * **Input**: * `limit` (optional) - number of messages per page. Min: 1, Max: 250. Default: 50 * `cursor` (optional) - pagination cursor from a previous response * `conversationId` (optional) - filter to a single conversation * `platform` (optional) - filter by platform: `instagram` * `accountId` (optional) - filter to a single connected account * **Output**: array of messages with `id`, `conversationId`, `direction`, `text`, `status`, `senderId`, `recipientId`, and `createdAt`. `direction` is `incoming` for messages you receive and `outgoing` for messages you send. Includes `cursor` for the next page when present. ### blotato\_get\_message Get a single message by its Blotato ID. Poll this after blotato\_send\_message to check whether an outgoing message reached `sent` or `failed`. * **Input**: `messageId` (required) - message ID from blotato\_list\_messages * **Output**: message object with `id`, `conversationId`, `direction`, `text`, `status`, `senderId`, `recipientId`, and `createdAt` ### blotato\_send\_message Send a direct message to one recipient, or a private reply to a comment. Blotato queues the message and sends it in the background. To check the status, poll with blotato\_get\_message. * **Input**: * `accountId` (required) - connected account to send from (from blotato\_list\_accounts) * `platform` (required) - `instagram` * `recipientId` (required) - the other party's id. Use an incoming message's `senderId` (from blotato\_list\_messages) * `text` (required) - message body. Instagram messages are limited to 1000 bytes * `commentId` (optional) - to send a private reply to a comment instead of a direct message, pass the comment's Blotato ID * **Output**: the queued message (poll with blotato\_get\_message) * **Status values**: queued -> processing -> sent | failed *** ## Content Extraction ### blotato\_create\_source Extract content from a URL or text. Polls internally for up to 20 seconds and returns the result directly. If still processing (e.g., a long YouTube video), returns the source ID -- use blotato\_get\_source\_status to poll for completion. * **Input**: * `sourceType` (required) - youtube, article, twitter, tiktok, text, audio, pdf, or perplexity-query * `url` (optional) - required for URL-based source types * `text` (optional) - required for text and perplexity-query source types * `customInstructions` (optional) - guide extraction (e.g., "focus on key takeaways", "summarize in 5 bullet points") * **Output**: id, status, title, content (extracted text), and referenceUrl ### blotato\_get\_source\_status Check the status of a source extraction. Use this if blotato\_create\_source timed out and returned an in-progress status. * **Input**: `id` (required) - source ID from blotato\_create\_source * **Output**: status, title, content (when completed), errorMessage (when failed) * **Status values**: queued -> processing -> completed | failed *** ## Videos and Images ### blotato\_list\_visual\_templates List all available visual templates (videos, carousels, quote cards, infographics). * **Input**: `search` (optional) - filter templates by title or description * **Output**: array of templates with ID, name, and description ### blotato\_create\_visual Generate an image, carousel, or video from a template. * **Input**: * `templateId` (required) - from blotato\_list\_templates * `prompt` (optional) - describe what you want in natural language * `render` (optional, default: true) * **Output**: visual ID and status (poll with blotato\_get\_visual\_status) ### blotato\_get\_visual\_status Check the status of a visual generation request. * **Input**: `id` (required) * **Output**: status, mediaUrl (for videos), imageUrls (for images/carousels) * **Status values**: queueing -> generating-script -> script-ready -> generating-media -> media-ready -> exporting -> done | failed *** ## Content Calendar ### blotato\_list\_schedules List all future scheduled posts, ordered by scheduled time (ascending). Supports cursor-based pagination. Each schedule includes the draft content (same structure as the `post` object in blotato\_create\_post), the scheduled time in UTC, and the target account information. * **Input**: * `limit` (optional) - number of schedules per page. Min: 1, Max: 50. Default: 20 * `cursor` (optional) - pagination cursor from a previous response * **Output**: array of schedules with ID, scheduledAt, account info, and draft content. Includes `count` (total) and `cursor` (for next page, if present). ### blotato\_get\_schedule Get a single scheduled post by ID. Returns the full schedule details including draft content, scheduled time, and account info. * **Input**: `id` (required) - schedule ID from blotato\_list\_schedules * **Output**: schedule object with ID, scheduledAt, account, and draft ### blotato\_update\_schedule Update a scheduled post's content, scheduled time, or both. At least one field is required. The scheduled time must be a valid ISO 8601 date string in the future. When the time changes, the post is re-queued for publishing at the new time. To update the post content, provide the same fields as blotato\_create\_post (accountId, platform, text, mediaUrls, and platform-specific fields). Send the full post object -- partial updates are not supported. * **Input**: * `id` (required) - schedule ID from blotato\_list\_schedules * `scheduledTime` (optional) - new ISO 8601 timestamp, must be in the future * `post` (optional) - updated post object with accountId, platform, text, mediaUrls, and platform-specific fields * **Output**: confirmation message ### blotato\_delete\_schedule Delete a scheduled post and cancel its publishing job. This action cannot be undone. * **Input**: `id` (required) - schedule ID from blotato\_list\_schedules * **Output**: confirmation message *** ## Media ### blotato\_create\_presigned\_upload\_url Get a presigned URL to upload a local file directly to Blotato. No intermediate storage (Google Drive, S3) required. * **Input**: `filename` (required) - filename with extension, used to determine content type (e.g., "photo.jpg", "video.mp4") * **Output**: `presignedUrl` (URL to PUT the file to, expires after a short period) and `publicUrl` (the final public URL to use in blotato\_create\_post) * **Max file size**: depends on your plan (see [Plan Limits](/settings/billing-and-credits.md#plan-limits)) * **Rate limit**: 120 requests per minute **How to use:** 1. Call `blotato_create_presigned_upload_url` with your filename 2. PUT the file contents to the returned `presignedUrl` with the correct Content-Type header 3. Use the returned `publicUrl` in blotato\_create\_post's `mediaUrls` field If your media is already at a public URL, you don't need to upload it first -- pass the URL directly into blotato\_create\_post's `mediaUrls` field. The presigned upload tool is for local files that don't have a public URL yet. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.blotato.com/api/mcp/tools.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.