Skip to content

Twitter Comments API

The Twitter Comments API — also described as the Twitter / X Comments API — lets a developer list, reply to, delete, and hide replies on tweets through one endpoint.

List Replies request
curl -X GET "{{API_BASE_URL}}/v1/comments/?platform=twitter&accountId=acc_tw_123&postId=TWEET_ID&limit=25" \
 -H "x-access-key: your-api-key"
Illustrative request
Example line 1

curl -X GET "{{API_BASE_URL}}/v1/comments/?platform=twitter&accountId=acc_tw_123&postId=TWEET_ID&limit=25" \

Illustrative request
Example line 2

-H "x-access-key: your-api-key"

On X a comment is a reply tweet, so the same operations cover both a reply to an original tweet and a reply to another reply, distinguished by whether you pass postId or commentId.

What a comment means on X and operations covered

On X, a comment is a reply tweet. That single fact shapes the whole API: listing returns replies to a tweet, replying can target either a tweet or another reply, deleting removes one of your own replies, and hiding moderates a reply on one of your tweets. The endpoint is shared with other platforms, so the platform value stays twitter and the targeting fields change meaning by operation.

Requests and responses by format

Use the List Replies request example to see the exact GET shape, including the trailing slash on /v1/comments/, the platform, accountId, postId, and limit query parameters, and the x-access-key header. The response example shows the 202 status context, the success flag, the comments array, and the nextCursor field for pagination. Keep the origin as {{API_BASE_URL}} and the path unchanged when you implement against this contract.

List Replies

List Replies fetches replies attached to a tweet, exposing who wrote each one, its wording, when it appeared, and its likeCount. Supply the tweet identifier through postId together with platform=twitter and the connected accountId. Discovery relies on recent search on X, reaching back roughly seven days, so very old replies may be absent even for an older tweet. Continue with nextCursor when more pages exist instead of assuming a single response is complete.

Reply to Tweets

For a reply to an original tweet, place the tweet ID in postId. For a reply to another reply, use commentId instead. Send POST /v1/comments/ with platform set to twitter, the connected accountId and the required text string; text must contain at least one character. The examples show the complete captured body fields. The posting workflow also supports replies through platformSpecificData.replyToTweetId. Use the comments route when the same workflow reads or moderates replies; use posting when the reply belongs to a broader publishing sequence.

Delete Replies

Delete one of your own reply tweets with DELETE /v1/comments/{commentId}, supplying platform=twitter and the connected accountId as required query parameters. The operation costs 3 credits and the documented 200 response is {"success": true}. Confirm the ID belongs to your own reply; this operation does not delete another account's reply. Verify ownership and the identifier before retrying a failed delete.

Hide Replies

Hide Replies conceals or restores a reply under one of your tweets, helping keep a thread tidy. Call PATCH /v1/comments/{commentId} with hidden: true to conceal and hidden: false to restore. This action requires tweet.moderate.write, so connections established before that scope existed need one reconnect to add it. When an older connection fails, reconnect first, then repeat the same PATCH request.

Token refresh behavior

X access tokens are short-lived, and the service refreshes and rotates them on every call. That reduces mid-session breakage in moderation workflows, but it is not a guarantee that every call succeeds: permission, ownership, and the 7-day recent-search window can still cause failures. Design retries around those specific checks instead of assuming token refresh alone fixes every error.

OAuth setup without own developer app

Connection uses the X OAuth flow, which asks for the scopes comment operations require. A separate X developer application is not needed on your side. When an operation needs a permission such as tweet.moderate.write, an account connected before that permission was added must reconnect once to grant it.

Credits per operation

A reply post is charged 5 credits, or 50 when its text includes a link. Reading replies is 1 credit for each call, removing a reply is 3 credits, and concealing or restoring one is 2 credits. Budget link-containing replies separately, since the link exception changes the cost of a reply post by a large factor.

Use cases for reply management

This endpoint suits teams that need one place to handle X replies: fetching them, answering people, cleaning up threads, and taking down your own posts. A typical flow lists replies for a tweet, replies to the ones that need an answer, hides the ones that should not be visible, and deletes your own reply when a correction is needed. Verify each step against its limit: recent replies only for listing, own replies only for deleting, and own tweets only for hiding.

Contract at a glance
OperationMethod and pathKey inputsCredits
List RepliesGET /v1/comments/platform=twitter, accountId, postId (tweet ID), limit1 per call
Reply to TweetsPOST /v1/comments/Required body: platform=twitter, accountId, text; target via postId or commentId5, or 50 if text contains a link
Hide RepliesPATCH /v1/comments/{commentId}Required body: platform=twitter, accountId, hidden; true hides, false unhides; needs tweet.moderate.write2
Delete RepliesDELETE /v1/comments/{commentId}Required query: platform=twitter, accountId; commentId is your own reply ID3

Exact methods and paths preserved from source; origin shown as {{API_BASE_URL}}.

List Replies response field map
FieldMeaning
successBoolean indicating the list call succeeded
commentsArray of reply objects
comments[].idReply tweet ID; use as commentId for reply-to-reply or hide
comments[].textReply text
comments[].author.idAuthor ID
comments[].author.nameAuthor name
comments[].timestampReply timestamp
comments[].likeCountLike count on the reply
comments[].hiddenHidden state; null in the example
nextCursorCursor for fetching the next page of replies

Field map from the supplied List Replies 202 response example.

Failure and limitation matrix
SituationLimit or checkWhat to do
Listing older repliesReplies found through X recent search, roughly the last 7 daysExpect older replies to be missing; do not treat an empty list as proof no older replies exist
Hiding with an older connectionNeeds tweet.moderate.writeReconnect once to grant the permission, then retry PATCH /v1/comments/{commentId}
Deleting a replyOnly one of your own replies by IDVerify ownership and ID before calling
Hiding a replyOnly a reply to one of your tweetsVerify the reply belongs to your tweet before calling
Short-lived X tokensTokens refreshed and rotated on every callStill check permission, ownership, and search-window failures on error

Limits stated in source; do not assume broader coverage.

Frequently asked questions

What do I pass as the postId for Twitter/X?

Supply the identifier of the original tweet. A GET request to /v1/comments/ with platform set to twitter, your connected accountId, and that identifier in postId returns replies attached to it. Coverage comes from recent search on X, spanning about a week.

How do I reply to a tweet or to another reply?

Send POST /v1/comments/ with platform set to twitter. Put the original tweet identifier in postId for a top-level reply, or put a reply identifier in commentId for a nested reply. Publishing alone can also be done through the Posting API using platformSpecificData.replyToTweetId, while the comments route suits workflows that also read or hide replies.

Can I hide replies on my tweets?

Yes, for replies under your own tweets. Call PATCH /v1/comments/{commentId} with hidden set to true to conceal one, or false to restore it. This moderation action requires tweet.moderate.write, so connections made before that scope existed need a single reconnect to add it.

Do I need my own X developer app?

No separate X developer application is needed on your side. Connection happens through the X OAuth flow, which asks for the scopes these comment operations require, after which the connected account can be used.

How much does the Twitter/X Comments API cost?

Charges are per operation: a reply post is 5 credits, rising to 50 when its text includes a link; reading replies is 1 credit for each call; removing a reply is 3 credits; concealing or restoring one is 2 credits.

What can I build with the Twitter/X Comments API?

Consider it when a product needs unified handling of X replies: fetching them, answering people, cleaning up threads, and taking down your own posts. That covers community tooling, client-facing dashboards, and automated support flows built around a single connected account.

List Replies 202 response
{
    "success": true,
    "comments": [
      {
        "id": "1797000000000000002",
        "text": "An example comment.",
        "author": { "id": "2233445566", "name": "Sam" },
        "timestamp": "2026-10-20T14:22:10Z",
        "likeCount": 2,
        "hidden": null
      }
    ],
    "nextCursor": "b26v89..."
}
Reply to a Tweet request using postId
curl -X POST "{{API_BASE_URL}}/v1/comments/" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "twitter",
  "accountId": "acc_tw_123",
  "postId": "TWEET_ID",
  "text": "An example comment."
}'
Reply to a Reply request using commentId
curl -X POST "{{API_BASE_URL}}/v1/comments/" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "twitter",
  "accountId": "acc_tw_123",
  "commentId": "1797000000000000002",
  "text": "An example comment."
}'
Hide a Reply request
curl -X PATCH "{{API_BASE_URL}}/v1/comments/{commentId}" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "twitter",
  "accountId": "acc_tw_123",
  "hidden": true
}'
Delete your own reply
curl -X DELETE "{{API_BASE_URL}}/v1/comments/{commentId}?platform=twitter&accountId=acc_tw_123" \
  -H "x-access-key: YOUR_API_KEY"
Documented delete response · HTTP 200
{
  "success": true
}