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:
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_countinGET /v1/inbox/commentsis 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_cursoruntilhas_moreisfalse. With alimitbelow 10, each page holds at mostlimitreplies, andnext_cursorskips the rest of that page’s 10. Use alimitof 10 or more when you page. - Filters.
moderation_status,order, andqdo not filter or sort X replies. An invalid value still returns400 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.
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 avalidation.*error or with429 platform.twitter.throttled: see When a credit comes back. Every otherplatform.twitter.*code and501 resource.not_supportedkeep the credit, including403 platform.twitter.forbidden,403 platform.twitter.duplicate_content, and429 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_requiredwitherror.meta.fieldset torequest_body, and the credit is returned. A reply whose text repeats a recent post of the account returns403 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.
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:401,403 auth.insufficient_scope. The API key is invalid, or a scoped key lacks the scope in Scopes.404 account.not_found,403 account.reconnection_required,401 platform.twitter.auth,401 platform.twitter.unauthorized. Theacc_ID is not yours, or the account needs reconnecting.401 platform.twitter.unauthorizedleaves the account working: if it persists, reconnect.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.403 account.permission_missing. The account lacks the permission the call needs:comments.readto list replies,comments.writeto reply, hide, unhide, or delete.error.meta.permissionnames it.403 platform.twitter.insufficient_scope. The X connection lacks a scope the call needs, for exampletweet.moderate.writeto hide. Reconnect the account.400 validation.field_required,400 validation.field_invalid. A required field is missing, or a parameter has a wrong value.error.meta.fieldnames it.request_bodymeans X refused the reply text.400 validation.id_invalid,400 validation.id_platform_mismatch. The comment ID is the wrong type or belongs to another platform: see IDs.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 with501 resource.not_supportedor403 platform.twitter.forbidden: hide it instead.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.402 platform.twitter.usage_capped. Your X app is out of credits or at its spending limit.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 theRetry-Afterheader 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 theRetry-Afterheader.
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 nocomment.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.
Related
- X / Twitter API: capabilities, connect rules, limits, and scopes for X
- X / Twitter direct messages: list and send X DMs
- X / Twitter publishing: publish posts, threads, and replies with
in_reply_to_tweet_id - Comments: the cross-platform comment endpoints and fields
- Use your own X app: the X app that X bills for every call
- Plans and usage: what costs an interaction credit