Skip to main content
SocialAPI reads the replies to the posts of a connected X account and acts on them: it replies to them, hides and unhides them, and deletes the replies the account wrote. X has no separate comment object: a comment is a post that replies to another post, and SocialAPI lists it with the same endpoints and fields as a comment on every other platform. The cross-platform rules are in Comments. A public reply costs 1 interaction credit. Reading, hiding, unhiding, and deleting cost no credits. X also bills every read and write to your own X developer app, because X connects through your own X app. X sends no comment events, so read new replies with the list endpoints.

Endpoints

{post_id} is the X post ID, for example 1846123456789012345: the id of a post in GET /v1/inbox/comments, or targets[].platform_post_id on a post you published through SocialAPI. {comment_id} and comment_id accept the reply’s sapi_cmt_ ID or its X post ID (platform_id). See IDs.

Your first request

List the replies to a post. account_id is required:
Response (HTTP 200):
The fields are described in List comments and replies. On X, is_owner, parent_id, is_hidden, liked_by_viewer, and every capabilities key hold the same value on every reply: see Fields that differ on X.

List the replies to a post

GET /v1/inbox/comments/{post_id} returns the replies in the post’s conversation, newest first. The list holds direct replies to the post and replies to those replies, at every depth, in one flat list. Reposts are left out.
  • 7-day window. X returns only replies posted in the last 7 days. A reply older than 7 days is not listed, whatever the age of the post. The post’s comment_count in GET /v1/inbox/comments is X’s reply count, which has no 7-day window, so it can be higher than the number of replies you can list.
  • Paging. Follow next_cursor until has_more is false. With a limit below 10, each page holds at most limit replies, and next_cursor skips the rest of that page’s 10. Use a limit of 10 or more when you page.
  • Filters. moderation_status, order, and q do not filter or sort X replies. An invalid value still returns 400 validation.field_invalid.
GET /v1/inbox/comments/{post_id}/{comment_id}/replies lists the direct replies to one reply, in the same shape, newest first. Its default limit is 10, the same 7-day window applies, and a limit above 100 is treated as 100. The paging rule above applies. A limit of 0 or less, or one that is not an integer, returns 400 validation.field_invalid. GET /v1/inbox/comments?account_id={account_id}&platform=twitter lists the account’s posts with their comment_count, which is X’s reply count. The list includes the replies the account published, because X treats each reply as a post. Reposts are left out. The parameters are in List posts with comments.

Fields that differ on X

Reply to a post or a reply

POST /v1/inbox/comments/{post_id} publishes a reply as the connected account. With comment_id, the reply answers that reply. Without it, the reply answers the post itself.
Response (HTTP 200):
comment_id in the response is the new reply’s sapi_cmt_ ID. The reply is a public X post, live when the call returns.
  • Cost. A reply costs 1 interaction credit. When the plan’s allowance is used up, the call returns 429 validation.interaction_limit_exhausted. The credit comes back when the request fails with a validation.* error or with 429 platform.twitter.throttled: see When a credit comes back. Every other platform.twitter.* code and 501 resource.not_supported keep the credit, including 403 platform.twitter.forbidden, 403 platform.twitter.duplicate_content, and 429 platform.twitter.rate_limit.
  • Who you can reply to. A reply to another account’s post goes through only when that post’s author mentioned the connected account or quoted one of its posts. X refuses other replies with 403 platform.twitter.forbidden.
  • Text X refuses. A reply X refuses as a post, for example one longer than X allows for the account (280 characters without X Premium), returns 400 validation.field_required with error.meta.field set to request_body, and the credit is returned. A reply whose text repeats a recent post of the account returns 403 platform.twitter.duplicate_content.

Hide and unhide a reply

POST /v1/inbox/comments/{post_id}/{comment_id}/hide hides a reply. X keeps a hidden reply reachable by its link and de-emphasizes it in the conversation view. DELETE on the same path, with account_id as a query parameter, unhides it.
Response (HTTP 200):
X lets the connected account hide only a reply in a conversation that the account’s own post started. Hiding a reply in another person’s conversation returns 501 resource.not_supported. Hiding and unhiding cost no credits. Hiding needs the tweet.moderate.write scope: see Scopes.

Delete a reply

DELETE /v1/inbox/comments/{post_id}/{comment_id}?account_id={account_id} deletes a reply the connected account wrote. It returns { "success": true }, costs no credit, and cannot be undone. X lets an account delete only its own posts. Deleting another person’s reply fails with 501 resource.not_supported or 403 platform.twitter.forbidden: hide it instead. can_delete is false on every X reply, so decide from author_username, not from can_delete.

What X does not allow

Limits

Past one of X’s rate limits, the call returns 429 platform.twitter.rate_limit, with a Retry-After header when X reports when the limit resets. The same code is returned when X is temporarily unavailable. See Rate limits.

Errors and debugging

Check these in order when an X comment call fails or returns nothing:
  1. 401, 403 auth.insufficient_scope. The API key is invalid, or a scoped key lacks the scope in Scopes.
  2. 404 account.not_found, 403 account.reconnection_required, 401 platform.twitter.auth, 401 platform.twitter.unauthorized. The acc_ ID is not yours, or the account needs reconnecting. 401 platform.twitter.unauthorized leaves the account working: if it persists, reconnect.
  3. 412 byok.app_access_denied, 401 byok.credentials_invalid. X refused your X app access to its API, or rejected the app credentials saved in SocialAPI. Fix the app as in Use your own X app, then reconnect the account.
  4. 403 account.permission_missing. The account lacks the permission the call needs: comments.read to list replies, comments.write to reply, hide, unhide, or delete. error.meta.permission names it.
  5. 403 platform.twitter.insufficient_scope. The X connection lacks a scope the call needs, for example tweet.moderate.write to hide. Reconnect the account.
  6. 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. request_body means X refused the reply text.
  7. 400 validation.id_invalid, 400 validation.id_platform_mismatch. The comment ID is the wrong type or belongs to another platform: see IDs.
  8. 403 platform.twitter.forbidden, 403 platform.twitter.duplicate_content. X refused the reply or the delete: the account was not mentioned or quoted by the author it replies to, or the text repeats a recent post of the account. Deleting another person’s reply fails with 501 resource.not_supported or 403 platform.twitter.forbidden: hide it instead.
  9. 501 resource.not_supported. X lacks the action (like, private reply, reply to a mention), the reply to hide is in another person’s conversation, or the reply to delete is another person’s.
  10. 402 platform.twitter.usage_capped. Your X app is out of credits or at its spending limit.
  11. 429 validation.interaction_limit_exhausted, 429 platform.twitter.rate_limit, 429 platform.twitter.throttled. validation.interaction_limit_exhausted: your plan’s interaction allowance is used up until the next billing period. Upgrade the plan to reply now. platform.twitter.rate_limit: X’s own limit. Wait for the Retry-After header when it is present. platform.twitter.throttled: X refused this account with its own rate limit, and SocialAPI refuses its calls until the wait ends. Wait for the Retry-After header.
When the list is empty, check that the post has replies from the last 7 days and that account_id is the account that published the post. The full catalog is in Errors.

Scopes

The X connection needs tweet.read and users.read to read replies, tweet.write to reply and delete, and tweet.moderate.write to hide and unhide. The full list is in X scopes.

Events

X sends no comment events, so SocialAPI emits no comment.received for X. Read new replies with GET /v1/inbox/comments/{post_id}. The events an X account does emit are in the Webhook events row of X capabilities.

Use from an AI agent

The tool list is in MCP tools.
Last modified on November 15, 2026