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.
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"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"
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.
| Operation | Method and path | Key inputs | Credits |
|---|---|---|---|
| List Replies | GET /v1/comments/ | platform=twitter, accountId, postId (tweet ID), limit | 1 per call |
| Reply to Tweets | POST /v1/comments/ | Required body: platform=twitter, accountId, text; target via postId or commentId | 5, or 50 if text contains a link |
| Hide Replies | PATCH /v1/comments/{commentId} | Required body: platform=twitter, accountId, hidden; true hides, false unhides; needs tweet.moderate.write | 2 |
| Delete Replies | DELETE /v1/comments/{commentId} | Required query: platform=twitter, accountId; commentId is your own reply ID | 3 |
Exact methods and paths preserved from source; origin shown as {{API_BASE_URL}}.
| Field | Meaning |
|---|---|
| success | Boolean indicating the list call succeeded |
| comments | Array of reply objects |
| comments[].id | Reply tweet ID; use as commentId for reply-to-reply or hide |
| comments[].text | Reply text |
| comments[].author.id | Author ID |
| comments[].author.name | Author name |
| comments[].timestamp | Reply timestamp |
| comments[].likeCount | Like count on the reply |
| comments[].hidden | Hidden state; null in the example |
| nextCursor | Cursor for fetching the next page of replies |
Field map from the supplied List Replies 202 response example.
| Situation | Limit or check | What to do |
|---|---|---|
| Listing older replies | Replies found through X recent search, roughly the last 7 days | Expect older replies to be missing; do not treat an empty list as proof no older replies exist |
| Hiding with an older connection | Needs tweet.moderate.write | Reconnect once to grant the permission, then retry PATCH /v1/comments/{commentId} |
| Deleting a reply | Only one of your own replies by ID | Verify ownership and ID before calling |
| Hiding a reply | Only a reply to one of your tweets | Verify the reply belongs to your tweet before calling |
| Short-lived X tokens | Tokens refreshed and rotated on every call | Still 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.
{
"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..."
}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."
}'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."
}'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
}'curl -X DELETE "{{API_BASE_URL}}/v1/comments/{commentId}?platform=twitter&accountId=acc_tw_123" \
-H "x-access-key: YOUR_API_KEY"{
"success": true
}