capabilities object.
A public reply costs 1 interaction credit. Reading, private replies, hiding, deleting, and liking cost none. Platform pages hold the rules that differ per platform.
Endpoints
{post_id} is the platform’s post ID (targets[].platform_post_id on a post you published through SocialAPI, or id from GET /v1/inbox/comments). {comment_id} and comment_id accept the comment’s sapi_cmt_ ID or the platform’s comment ID. See IDs.
Your first reply
List the posts that have comments on one account:account_id is required:
comment_id in the response is the new reply’s sapi_cmt_ ID.
List posts with comments
GET /v1/inbox/comments returns the connected accounts’ posts with their comment counts, newest published first. Add min_comments=1 to keep only posts that have comments.
Each post has
id (the platform’s post ID, the value for {post_id}), user_id (the ID of your SocialAPI account), account_id, page_id (Facebook only), platform, content, thumbnail, permalink, comment_count, like_count, published_at, created_at, and updated_at. pagination holds has_more, and next_cursor when has_more is true. Paging is in Pagination.
List comments and replies
GET /v1/inbox/comments/{post_id} lists the comments on a post. GET /v1/inbox/comments/{post_id}/{comment_id}/replies lists the replies to one comment in the same shape. Both need account_id, the connected account that owns the post. A missing account_id returns 400 validation.field_required.
A page can hold fewer comments than
limit, because the platform sets its own page size. Follow next_cursor until has_more is false: see Pagination.
Comments in webhook events use the nested Interaction shape instead of this flat one.
Read
capabilities instead of assuming. A call the platform does not support returns 501 resource.not_supported.
Reply to a comment
POST /v1/inbox/comments/{post_id} posts a public reply.
A reply costs 1 interaction credit. When the plan’s interaction allowance is used up, the call returns
429 validation.interaction_limit_exhausted. A credit is returned when the request fails with a validation.* error: see When a credit comes back.
Send a private reply
A private reply is a DM to the person who wrote a comment. It has its own endpoint:POST /v1/inbox/comments/{post_id}/{comment_id}/private-reply. The reply endpoint above never sends one.
A private reply is a single message, so it carries either
text (with optional buttons) or one attachment. Sending attachment with text or buttons returns 400 validation.attachment_conflict. If the platform cannot fetch or accept the file, the call returns 422 platform.instagram.attachment_failed or 422 platform.facebook.attachment_failed, and the comment can still receive its private reply. To send a PDF as the first message:
400 platform.instagram.private_reply_ineligible or 400 platform.facebook.private_reply_ineligible. When the platform refuses the reply, error.meta.fbtrace_id holds Meta’s trace ID for Meta support when Meta sends one. When the comment is already known to be ineligible, the error instead carries error.meta.blocked_locally: true and error.meta.reason: already_replied, platform_refused, or window_expired. When error.meta.blocked_locally is true, or the reply was text only, this 400 is final. When the platform refuses a reply that carried buttons or an attachment, the refusal can come from that content: send it once more as text only. Every other platform returns 501 resource.not_supported.
A private reply does not open the messaging window. You cannot message the person again until they answer, and their answer opens the window.
To answer comments by keyword with no handler of your own, use an Automation: it sends the private reply and handles each button tap, including a Follow gate on Instagram.
Hide and unhide a comment
Hiding removes a comment from public view. Unhiding restores it.DELETE on the same path and account_id as a query parameter:
501 resource.not_supported. Facebook refuses to hide or unhide some comments, for example a comment the Page’s moderation filters already hid. That refusal returns 422 platform.facebook.comment_not_hideable, and retrying does not help. Threads hides replies only on an account connected on or after 2026-10-17: reconnect an older account first. See Threads comments.
Delete a comment
DELETE /v1/inbox/comments/{post_id}/{comment_id}?account_id={account_id} deletes the comment on the platform. It returns { "success": true } and cannot be undone. On Threads, TikTok, X, Bluesky, and YouTube, you can delete only comments the connected account wrote. Each other platform’s page states its rule.
Like and unlike a comment
POST /v1/inbox/comments/{post_id}/{comment_id}/like likes a comment as the connected account. DELETE on the same path removes the like. Both take account_id: in the body for POST, as a query parameter for DELETE. They return { "success": true }. A platform without comment likes returns 501 resource.not_supported, and can_like is false on its comments.
Filter YouTube comments
GET /v1/inbox/comments/{post_id} accepts 3 more parameters. Only YouTube uses them to filter or sort. On TikTok, a q or a non-default order or moderation_status stops hidden comments from being added to the list: see TikTok comments.
A value outside these lists, or a longer
q, returns 400 validation.field_invalid. See YouTube comments.
Platform support
Every platform has its own comment rules: whether replies nest, who can hide or delete what, and which account permissions and platform scopes the connection needs. The capability matrix compares platforms, and each platform has a comments page with the details: Instagram, Facebook, Threads, TikTok, LinkedIn, YouTube, X, and Bluesky. Google Business Profile has no comments or Q&A: its calls return501 resource.not_supported. Read reviews on Reviews.
Limits
Errors and debugging
Check these in order when a comment call fails or returns nothing:401,403 auth.insufficient_scope. The key is invalid, or a scoped key lacks the scope in Scopes.404 account.not_found,403 account.reconnection_required. Theacc_ID is not yours, or the account needs reconnecting.403 account.permission_missing. The account lacks the permission the call needs:comments.readto list the comments on a post and the replies to a comment,comments.writeto reply, hide, unhide, delete, or like, andmessages.writefor a private reply.error.meta.permissionnames it.GET /v1/inbox/commentsnever returns this error. Withoutcomments.read, posts the account makes outside SocialAPI are not added to the list, and removingcomments.readdeletes the posts already in it, including posts published through SocialAPI: see Removing a permission deletes data.400 validation.field_required,400 validation.field_invalid. A required field is missing, or a parameter has a wrong value.error.meta.fieldnames it.400 validation.id_invalid,400 validation.id_platform_mismatch. The comment ID is the wrong type or belongs to another platform: see IDs.501 resource.not_supported. The platform lacks the action. Readcapabilitieson the comment.404 resource.not_found. The post was deleted on the platform. The same post returns the same 404 afterwards.400 platform.instagram.private_reply_ineligible,400 platform.facebook.private_reply_ineligible. The comment already received its private reply, or is older than 7 days. Whenerror.meta.blocked_locallyistrue, or the reply was text only, this 400 is final. When the platform refuses a reply that carriedbuttonsor an attachment, the refusal can come from that content: send it once more as text only.429 validation.interaction_limit_exhausted,429 platform.{platform}.rate_limit.interaction_limit_exhaustedmeans the plan’s interaction allowance is used up untilperiod_end: upgrade the plan to continue sooner, see Plans and usage.rate_limitis the platform’s own limit: wait for theRetry-Afterheader when it is present, see Rate limits.429 messaging.velocity_limitand429 platform.{platform}.throttled: wait for theRetry-Afterheader, then retry.422 platform.youtube.processing_failure. On a delete, YouTube refused because your channel did not write the comment: hide it instead. On a hide or a moderation, the commenter already deleted the comment, or YouTube could not process the request: retry once, and stop if it repeats.422 platform.facebook.comment_not_hideable. Facebook refused to hide or unhide the comment, for example a comment the Page’s moderation filters already hid. Retrying does not help.
account_id owns the post, and, on a platform that sends events, that the comment arrived: see Webhook events. The full catalog is in Errors.
Scopes
Events
SocialAPI sendscomment.received when a person comments on a post of a connected account, on the platforms that report comments to SocialAPI. See comment.received for the platforms and the payload. Platforms that report nothing, such as X, YouTube, and Bluesky, need the list endpoints above. An account without the comments.read permission receives no comment.received events.
Use from an AI agent
The tool list and error shape are in MCP tools.
Related
- Direct messages: the messages and buttons a private reply starts.
- Automations: answer comments by keyword with no handler of your own.
- Webhook events: the
comment.receivedpayload per platform. - Platform support: which platform supports which comment action.
- IDs: the
sapi_cmt_ID and the platform IDs these endpoints accept. - Account permissions: the permissions an account needs for each comment action.
- Plans and usage: what costs an interaction credit.