Tools reference
The Blotato MCP Server exposes 32 tools. Use the connected tool's input schema for its arguments. Start with client setup or choose an agent workflow.
Call blotato_list_accounts before publishing. Follow completion rules after submitting a post, source, comment, or message. REST JSON bodies and MCP tool arguments have different shapes.
Accounts
For every tool's required and optional argument names, see the MCP input index. The sections below explain behavior and results.
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 nameOutput: 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_accountsOutput: array of boards with
idandname. UseidasboardIdin blotato_create_post.
Credits
blotato_get_credits
Get the account's remaining credits, the account email the API key belongs to, and current pricing (price per 1,000 credits and the min/max purchase quantity). If the user wants more credits, state the returned account email, then direct them to Settings > Billing. Credits are non-transferable between accounts.
Output:
creditsRemaining,accountEmail,purchaseQuantityRange(minandmax), andpricePer1000CreditsUsd.
Publishing
blotato_create_post
Create and publish (or schedule) a post to a social media platform.
Input:
accountId(required) - from blotato_list_accountsplatform(required) - twitter, instagram, facebook, tiktok, linkedin, pinterest, bluesky, threads, or youtubetext(required) - post contentmediaUrls(optional) - array of public media URLsscheduledTime(optional) - ISO 8601 datetimeuseNextFreeSlot(optional) - use next available schedule slotpageId(optional) - for Facebook/LinkedIn pagesmediaType(optional) - for Instagram/Facebook: reel or story. Facebook videos must be"reel"(regular feed videos no longer supported).trial(optional) - for Instagram reels: object withgraduationStrategy("MANUAL"or"SS_PERFORMANCE"). Trial reels are shown to non-followers first.firstComment(optional) - for Facebook/Instagram: text auto-posted as the first comment right after publishing. Not supported for stories. Useful for links.privacyLevel(optional) - for TikTokadditionalPosts(optional) - array of additional posts for threads (Twitter, Bluesky, Threads). Each entry hastextandmediaUrls. The first post uses the top-leveltextandmediaUrlsfields. Blotato handles reply chaining.boardId(optional) - for Pinterest (get from blotato_list_pinterest_boards)title(optional) - for Pinterest or YouTubeprivacyStatus(optional) - for YouTube: public, private, or unlistedplaylistIds(optional) - for YouTube: array of playlist IDs from blotato_list_accounts to add the video to playliststhumbnailUrl(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 available on a published result), errorMessage (when failed)
Status values: in-progress -> published | scheduled | failed
in-progress also covers a lookup with no matching result record. It does not validate a guessed ID or confirm a live queue job. Use the original submission ID, keep a polling limit, and follow post lifecycle.
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 an account field and a state field with a type of scheduled, published (includes postUrl and analytics), or failed (includes errorMessage). account is null when the connected account no longer exists. Published-post analytics are null until metrics have been collected.
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: 50cursor(optional) - pagination cursor from a previous responsestatus(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,account, and astateobject. A published state includesanalytics.latestandanalytics.history, oranalytics: null. Includescursorfor 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) - the MCP tool acceptstwitter,instagram,facebook,threads, orblueskyas an explicit filter. Omit to include all available results. The REST analytics endpoint also accepts TikTok, YouTube, and Pinterest filters. The MCP filter list is narrower than the backend's collection coverage.sortBy(optional) - metric to rank by:likes_count,comments_count,views_count, orreach_count. Defaults toviews_count. For Twitter/X, comments ranking usesreplies_countwhen comments are not reported, and views ranking usesimpressions_countwhen views are not reported.limit(optional) - number of posts to return. Min: 1, Max: 100. Default: 20
Output: array of
items, each withid,content,postUrl,platform,createdAt,mediaUrls,latestMetrics, andmetricsHistory.
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_postsOutput:
publishedPostId,platform,lastFetchedAt,lastError,metrics(latest, or null when not synced yet), andhistory(array of snapshots, each withfetchedAtandmetrics).
Comments
Read and post comments on your published Instagram and Facebook 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: 50cursor(optional) - pagination cursor from a previous responseplatform(optional) - filter by platform:instagramorfacebookaccountId(optional) - filter to a single connected accountparentCommentId(optional) - filter to direct replies to a single commentpostId(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 timestampuntil(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, anderrorMessage(when failed). Includescursorfor the next page when present.
blotato_get_comment
Get a single comment by its Blotato ID.
Input:
commentId(required) - comment ID from blotato_list_commentsOutput:
id,text,status,isAuthor,platform,postId,createdAt, anderrorMessage(when failed)
blotato_post_comment
Post a comment on one of your published Instagram or Facebook 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 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, Facebook up to 8000parentCommentId(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 and Facebook Page. 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: 50cursor(optional) - pagination cursor from a previous responseplatform(optional) - filter by platform:instagramorfacebookaccountId(optional) - filter to a single connected account
Output: array of conversations with
id,platform,participants,updatedAt, andcreatedAt. Includescursorfor the next page when present.
blotato_get_conversation
Get a single conversation by its Blotato ID.
Input:
conversationId(required) - conversation ID from blotato_list_conversationsOutput: conversation object with
id,platform,participants, andupdatedAt
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: 50cursor(optional) - pagination cursor from a previous responseconversationId(optional) - filter to a single conversationplatform(optional) - filter by platform:instagramorfacebookaccountId(optional) - filter to a single connected account
Output: array of messages with
id,conversationId,direction,text,payload,status,senderId,recipientId, andcreatedAt.directionisincomingfor messages you receive andoutgoingfor messages you send. Includescursorfor 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_messagesOutput: message object with
id,conversationId,direction,text,payload,status,senderId,recipientId, andcreatedAt
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) -instagramorfacebookpageId(required for Facebook) - the Facebook Page to send from (from the account's subaccounts via blotato_list_accounts)recipientId(required) - the other party's id. Use an incoming message'ssenderId(from blotato_list_messages)text(required) - message body. Instagram messages are limited to 1000 bytes, Facebook to 2000 characters. Withbuttonsset, the limit drops to 640 characterscommentId(optional) - to send a private reply to a comment instead of a direct message, pass the comment's Blotato IDbuttons(optional) - Facebook and Instagram only. 1 to 3 call-to-action buttons pinned under the message. See Buttons and Quick RepliesquickReplies(optional) - Facebook and Instagram only. 1 to 13 tappable reply chips. See Buttons and Quick Replies
Output: the queued message (poll with blotato_get_message)
Status values: queued -> processing -> sent | failed
Buttons and Quick Replies
Facebook and Instagram messages may be sent with attached buttons or quick replies via buttons or quickReplies. They are mutually exclusive - pass one or the other, never both.
Buttons sit under the message and stay there. Each has:
type-web_urlopens a link,postbackreports the tap back to youtitle- button label, 1 to 20 charactersurl- required forweb_url, starts withhttps://payload- required forpostback, 1 to 1000 characters
Blotato supports web_url and postback buttons. Phone buttons are not supported.
Instagram renders buttons in the mobile app only. A recipient reading the conversation on instagram.com in a desktop browser sees the message text with no buttons. Pass buttons or a URL inside text, not both, since a message carrying both leaves the URL unclickable on desktop. For a desktop audience, drop buttons and put the URL in text.
Quick replies are tappable chips offered as canned answers. They disappear once the person taps one or types their own message. Each has a title (1 to 20 characters) and a payload (1 to 1000 characters).
Reading a tap. Both kinds of tap arrive as the next incoming message carrying payload.selection, readable with blotato_list_messages. A quick-reply tap sends a real text message, so text holds the chip label. A postback sends no text message: the tap is recorded as an incoming message with text set to the button label. Either way, branch on selection.payload rather than text, since two chips sharing a label are distinguishable only by payload. A web_url button produces no selection.
Reconnect for postback buttons. Blotato subscribes your account to the postback webhook when you connect it. If you connected your account before buttons were launched, reconnect to start receiving postback events. Quick-reply taps need no reconnect.
See Buttons and Quick Replies for the REST equivalent.
Automations
Create and manage DM automations on Instagram and Facebook Pages. An automation sends one direct message when someone comments on your post or sends your account a message. See DM Automations.
An automation sends one message by default. Three optional steps extend it, and Blotato runs them in a fixed order: a follow gate (Instagram only), an email gate, your message, then a webhook.
Every live automation whose trigger matches starts its own run. Two automations matching the same comment both try to answer it, and only one reply reaches the person. Keep one live automation per keyword on each account. Messages without text, such as photos or stickers, never start a run.
Every DM an automation sends counts toward your plan's monthly active-contacts limit. Gate messages go to the same person, so one contact still counts once. See Active Contacts.
blotato_create_automation
Create a DM automation. It starts as an inactive draft unless isActive is true. You can add an email gate, an Instagram follow gate, or a webhook.
Input:
accountId(required) - Instagram or Facebook account from blotato_list_accountsplatform(required) -instagramorfacebookpageId(required for Facebook) - the Facebook Page from the account's subaccountsname(required) - automation label, 1 to 60 characterstriggers(optional) - up to 2 triggers, at most onecomment-receivedand onemessage-received. Each hastype,keywords(omit or empty to match any comment or text message),postId(comment triggers only, the tracked Blotato post ID, not the native platform ID), andisActive(default true). For an externally published Instagram post already tracked through an incoming comment, use the comment's non-nullpostIdafter verifying the account andplatformPostId. OmittingpostIdmatches any post and requires approval for this scope. See post targeting. Any one trigger firing starts a single run. Omittriggersfor a draft with no triggersdmMessage(required) - the message sent when a trigger fires, 1 to 640 charactersbuttons(optional) - up to 3 link buttons, each withtype: "url", atitleof 20 characters or fewer, and aurlfollowGate(optional, Instagram only) -message(1 to 640 characters) andbuttonTitle(20 characters or fewer, defaultI'm following). Holds the DM back until the contact follows the account. Rejected on a Facebook automationemailGate(optional) -message(1 to 640 characters). Holds the DM back until the contact replies with an email address. On automations published after September 14, 2026, a contact with an email already on file skips itwebhook(optional) -method(GET,POST,PUT,PATCH, orDELETE),url(publichttp(s), 2048 characters or fewer), andheaders(optional). Called once the DM sendsisActive(optional) - true publishes it immediately. Default false
Output: the created automation
Follow gate. Blotato sends the gate message with a confirm button, waits up to 30 days for a reply, then reads follower status. A contact who does not follow gets the gate message again. An unknown status sends the DM anyway, since Instagram withholds follower status for a contact who never granted profile access. A confirmed follow is reused for 30 days, but the gate message still goes out on every run.
Any text reply advances the follow gate, so the button tap is a shortcut rather than a requirement. Two setup points to pass on to the user. The Instagram account needs reconnecting if they connected it before DM automations and follow gating landed, since Blotato subscribes to button-tap events at connect time and an older connection does not reliably receive them, leaving runs to expire. Instagram also renders the confirm button in the mobile app only, so write the gate message to ask for a typed reply such as "Reply FOLLOWING once you have" in the message text.
Email gate. Blotato sends the gate message, waits up to 72 hours, and reads the first email address out of the reply. A reply holding no address returns the gate message. A match saves to the contact, then the DM sends. A contact with an email already on file skips the gate, and the DM sends with no gate message. This applies to automations published after September 14, 2026. An automation published earlier asks every time until you pass its current triggers to blotato_update_automation. Use a webhook to export the stored contact email. Conversation and message responses have no dedicated captured-email field, although the original reply remains available as message text.
Webhook. Every method except GET carries a JSON body with two keys, with or without a gate on the automation: {"email": "them@example.com", "isFollower": true}. email is the address on file for the contact, captured by an email gate, and null when Blotato holds none. isFollower is the follower status a follow gate last recorded, and null when Blotato never checked. GET carries no body. The host must resolve to a public address, redirects are not followed, and the timeout is 15 seconds. A non-2xx response or a timeout gets logged and the run still completes, with no retry. A blocked address, a DNS failure, or a connection error fails the run with error code 20304.
blotato_list_automations
List your DM automations, ordered by creation time (most recent first). Supports cursor-based pagination and selected analytics metrics.
Input:
limit(optional) - number of automations per page. Min: 1, Max: 250. Default: 50cursor(optional) - pagination cursor from a previous response
Output: array of automations with
id,accountId,name,platform,target,triggers(each withid,type,keywords,postId, andisActive),dmMessage,buttons,emailGate,followGate,webhook,isActive,publishedVersionId,createdAt,updatedAt, andstats.statscontainstriggered,completed, andfailedcounts from the last 24 hours pluslastRunAt, which is null when the automation has never run. Archived automations do not appear. Includescursorfor the next page when present.
blotato_update_automation
Update a DM automation. Any of name, triggers, dmMessage, buttons, followGate, emailGate, or webhook you pass replaces that field. Omitted fields stay unchanged. Pass null to remove a gate or a webhook. triggers replaces the whole trigger set, and [] removes every trigger.
Content changes to a live automation publish immediately. Changes to a draft stay saved until you pass isActive true. A live automation needs at least one active trigger, so to clear every trigger pass an empty triggers array and isActive false in the same call. To remove one trigger, pass triggers holding the trigger you keep. To update a single trigger without other changes, use blotato_update_automation_trigger.
Input:
automationId(required) - automation ID from blotato_list_automationsname(optional) - new automation label, 1 to 60 characterstriggers(optional) - replaces every trigger. Up to 2, at most one per type.[]removes alldmMessage(optional) - replaces the message textbuttons(optional) - replaces the link buttons.[]removes allfollowGate(optional, Instagram only) - replaces the follow gate. Pass null to remove itemailGate(optional) - replaces the email gate. Pass null to remove itwebhook(optional) - replaces the webhook. Pass null to remove itisActive(optional) - true publishes, false moves to draft. Omit to keep the current state
Output: the updated automation
blotato_update_automation_trigger
Update a single trigger on a DM automation, for example to turn it on or off. The change applies immediately on a live automation, with no republish. At least one trigger must stay on while the automation is live. To pause the whole automation, pass isActive false to blotato_update_automation instead.
Trigger IDs change whenever the automation's content or triggers are updated. Read them from blotato_list_automations or from the automation blotato_update_automation returns.
Input:
automationId(required) - automation ID from blotato_list_automationstriggerId(required) - trigger ID from the automation'striggersisActive(required) - true turns the trigger on, false turns it off
Output: the updated trigger
blotato_delete_automation
Archive a DM automation and stop new runs. Existing runs, including waiting gates, remain able to continue. Archiving does not cancel messages already queued. Archive only when requested. The archived automation no longer appears in blotato_list_automations.
Input:
automationId(required) - automation ID from blotato_list_automationsOutput: the archived automation
blotato_list_automation_runs
List the execution runs of one automation, ordered by start time (most recent first). A run is one execution: one comment or message matched a trigger. Use it to check whether an automation fires and why a reply did not go out.
Input:
automationId(required) - automation ID from blotato_list_automationslimit(optional) - number of runs per page. Min: 1, Max: 250. Default: 50cursor(optional) - pagination cursor from a previous responsestatus(optional) - array of statuses to include:running,waiting,completed,expired,superseded,failed. Omit to include allsince(optional) - ISO 8601 timestamp. Only runs with activity at or after this time are returned
Output: array of runs with
id,contactId,platform,status,error(when failed),createdAt, andupdatedAt. A failed run'serrorincludescode,message, and, when available,actionanddetailswith recovery contextStatus values: running, waiting, completed, expired, superseded, failed. A run expires when the contact never answers a gate inside its window: 30 days for a follow gate, 72 hours for an email gate. A run also expires when its message never settles within 30 minutes. A run is superseded when a newer run starts waiting on the same contact
blotato_list_automation_logs
List the execution logs written as an automation's runs advance, ordered by creation time (most recent first).
Input:
automationId(required) - automation ID from blotato_list_automationsflowRunId(optional) - filter to a single run, from blotato_list_automation_runslimit(optional) - number of logs per page. Min: 1, Max: 250. Default: 50cursor(optional) - pagination cursor from a previous response
Output: array of logs with
id,flowRunId,nodeId,level(info,warning,error),message,context, andcreatedAt
blotato_get_automation_analytics
Get analytics for one automation. triggered, completed, and failed are all-time totals. issues counts runs that failed during the last 7 days and is a subset of failed. A run ending on an error after the DM sends counts as failed. Runs still in flight, and runs ending as expired or superseded, count toward triggered but not toward completed or failed.
Input:
automationId(required) - automation ID from blotato_list_automationsOutput:
triggered,completed,failed,issues
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-queryurl(optional) - required for URL-based source typestext(optional) - required for text and perplexity-query source typescustomInstructions(optional) - guide extraction (e.g., "focus on key takeaways", "summarize in 5 bullet points")
Output:
idand status. A completed result includestitle,content, andreferenceUrlwhen available. Extraction failure from this create tool is an MCP error containing the source ID.
Long source content ends with [output truncated] when it exceeds the MCP response budget. A completed job does not prove the tool returned the full text. For complete content, use an authorized REST lookup with the same ID. Repeating the MCP status call does not paginate the text. See Extract and repurpose content.
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_sourceOutput:
id, status,titleandcontentwhen completed,messagewhen failed. Completed content is subject to the same truncation behavior as the create tool.Status values: queued -> processing -> completed | failed
An extraction failed result from this status tool is returned in JSON without an MCP isError flag. Inspect status as well as the tool error flag.
Videos and Images
Visual generation through MCP is not supported at this time. Create images, carousels, and videos in the web app or with the REST Create Visual endpoint. Then pass the finished media URLs to blotato_create_post in mediaUrls.
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: 20cursor(optional) - pagination cursor from a previous response
Output: array of schedules with ID, scheduledAt, account info, and draft content. Includes
count(total) andcursor(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_schedulesOutput: 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, call blotato_get_schedule first, then send the full post as a replacement. accountId, platform, and text are required. Fields you leave out are not kept, and leaving out mediaUrls removes the post's media. Omit post to change only the time.
Input:
id(required) - schedule ID from blotato_list_schedulesscheduledTime(optional) - new ISO 8601 timestamp, must be in the futurepost(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_schedulesOutput: 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) andpublicUrl(the final public URL to use in blotato_create_post)Max file size: depends on your plan (see Plan Limits)
Rate limit: 120 requests per minute
How to use:
Call
blotato_create_presigned_upload_urlwith your filenamePUT the file contents to the returned
presignedUrlwith the correct Content-Type headerUse the returned
publicUrlin blotato_create_post'smediaUrlsfield
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.
Last updated