Skip to main content
SocialAPI’s comments API reads the comments on the posts of your connected accounts and acts on them: reply publicly, send a private reply, hide, unhide, delete, and like. The endpoints are the same on every platform that has comments, and each comment tells you which actions the platform allows for it in its 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:
Response (HTTP 200):
Read the comments on that post. account_id is required:
Response (HTTP 200):
Reply to that comment:
Response (HTTP 200):
The reply is public when the platform accepts it. 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.
Response (HTTP 200):
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:
Private replies exist on Instagram and Facebook. The platform allows 1 private reply per comment, within 7 days of the comment. A second reply, or a comment older than 7 days, returns 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.
Response (HTTP 200):
Unhide with DELETE on the same path and account_id as a query parameter:
Hiding is free. A platform without it returns 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 return 501 resource.not_supported. Read reviews on Reviews.

Limits

Errors and debugging

Check these in order when a comment call fails or returns nothing:
  1. 401, 403 auth.insufficient_scope. The key is invalid, or a scoped key lacks the scope in Scopes.
  2. 404 account.not_found, 403 account.reconnection_required. The acc_ ID is not yours, or the account needs reconnecting.
  3. 403 account.permission_missing. The account lacks the permission the call needs: comments.read to list the comments on a post and the replies to a comment, comments.write to reply, hide, unhide, delete, or like, and messages.write for a private reply. error.meta.permission names it. GET /v1/inbox/comments never returns this error. Without comments.read, posts the account makes outside SocialAPI are not added to the list, and removing comments.read deletes the posts already in it, including posts published through SocialAPI: see Removing a permission deletes data.
  4. 400 validation.field_required, 400 validation.field_invalid. A required field is missing, or a parameter has a wrong value. error.meta.field names it.
  5. 400 validation.id_invalid, 400 validation.id_platform_mismatch. The comment ID is the wrong type or belongs to another platform: see IDs.
  6. 501 resource.not_supported. The platform lacks the action. Read capabilities on the comment.
  7. 404 resource.not_found. The post was deleted on the platform. The same post returns the same 404 afterwards.
  8. 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. 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.
  9. 429 validation.interaction_limit_exhausted, 429 platform.{platform}.rate_limit. interaction_limit_exhausted means the plan’s interaction allowance is used up until period_end: upgrade the plan to continue sooner, see Plans and usage. rate_limit is the platform’s own limit: wait for the Retry-After header when it is present, see Rate limits. 429 messaging.velocity_limit and 429 platform.{platform}.throttled: wait for the Retry-After header, then retry.
  10. 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.
  11. 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.
When the list is empty, check that the post has comments, that 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 sends comment.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.
Last modified on November 15, 2026