List Comments API
The List Comments API retrieves comments and first-level replies for one post on Facebook, Instagram, Threads, LinkedIn, YouTube, or Twitter/X. Use it for moderation queues, support triage, engagement review, and reply planning for a single item rather than activity across many posts.
List Comments API overview and supported platforms
This endpoint works on a single item at a time. You name the network through platform, the linked integration through accountId, and the item through postId. Six values are accepted for platform: facebook, instagram, threads, linkedin, youtube, and twitter. Identifier meaning shifts by network: on YouTube, postId carries the video identifier; on Twitter/X, it carries the tweet identifier; elsewhere it carries the post identifier on that network. Before calling, check that accountId points to an integration linked for the chosen platform, since identical identifier strings can refer to different objects across networks.
Request: GET {{API_BASE_URL}}/v1/comments
Issue a GET request to {{API_BASE_URL}}/v1/comments and include the x-access-key header with your access key. The example titled List comments request example brings the method, path, header placeholder, and query string together in one place. Every call needs platform, accountId, and postId. Two further parameters are optional: limit controls how many comments come back, and after carries a cursor when you continue an earlier result set. Omitting limit yields the documented default of 25; supplying it means staying inside the 1 to 100 range. Supply after only when continuing from a prior response.
Query parameters field map
The table titled Query parameters field map enumerates each parameter alongside its type, whether it is required, and what it means. Begin with the three required values, since without them the target thread is not identified. Add limit to request a different page size, and add after to resume. Treat after as an opaque token rather than a page number: copy the nextCursor value from the previous response verbatim and send it back unchanged. Avoid reusing a token obtained for a different platform, account, or post.
Platform-specific postId and permission notes
Each network adds its own conditions. Threads calls need threads_manage_replies granted, so a well-formed request can still fail on permissions. LinkedIn calls need Community Management social-feed scopes; integrations linked before comment support existed lack those scopes until the account is linked again, which grants the newer permissions. Twitter/X differs on coverage and cost: its replies are sourced through X recent search, spanning roughly the last 7 days, and an X plan that includes search access is needed. Listing Twitter replies also costs 1 credit, unlike the other platforms. Verify these conditions early, because they account for failures that request shape alone cannot explain.
Response field map and pagination
A successful payload carries success, a comments array, and nextCursor. Individual comments may carry id, text, author, timestamp, likeCount, hidden, and replies. Author is an object holding id and name. Replies nested inside a comment carry id, text, author, timestamp, and likeCount. The example titled List comments response example illustrates one comment containing one first-level reply, with likeCount present on both levels. Use hidden on a top-level comment to see whether it is marked hidden, and do not assume replies expose every field their parent does.
Pagination with nextCursor and after
Paging relies on a cursor. A non-null nextCursor means more results exist: send that value as after on the following request, as illustrated by the example titled Pagination request using nextCursor as after. A null nextCursor signals the end of the result set, so further paging requests should stop. Keep platform, accountId, postId, and limit steady across a sequence.
Worked example and edge cases
The table titled Failure and edge checks gives a validation sequence to run before treating output as complete. Confirm platform holds one of the six accepted values and that accountId and postId are present. Confirm any supplied limit is an integer between 1 and 100. Then confirm network conditions: threads_manage_replies for Threads, relinked Community Management social-feed scopes for LinkedIn, and for Twitter/X the roughly 7-day X recent search window, an X plan with search access, and the 1-credit cost. Finally confirm paging state: no after on a first request, a reused nextCursor as after to continue, and null nextCursor to finish. No error codes are stated here because the captured contract does not provide them; record the actual status and body returned during implementation testing.
| Parameter | Type | Required | Description |
|---|---|---|---|
| platform | string | Yes | facebook, instagram, threads, linkedin, youtube, or twitter |
| accountId | string | Yes | Integration ID from list_integrations |
| postId | string | Yes | Platform post ID; for YouTube pass the video ID, for Twitter/X pass the tweet ID |
| limit | integer | No | Max comments to return (1–100, default 25) |
| after | string | No | Pagination cursor from a previous response; pass the previous nextCursor value |
Source contract preserved exactly; origin modularized as {{API_BASE_URL}}.
| Platform | postId meaning | Permission or coverage note | Credit note |
|---|---|---|---|
| Platform post ID | Connected Facebook Page | No per-call credit exception stated in captured contract | |
| Platform post ID | Connected Instagram Business account | No per-call credit exception stated in captured contract | |
| threads | Platform post ID | Requires threads_manage_replies | No per-call credit exception stated in captured contract |
| Platform post ID | Requires Community Management social-feed scopes; accounts connected before comment support shipped must reconnect to grant them | No per-call credit exception stated in captured contract | |
| youtube | Video ID | Connected YouTube video | No per-call credit exception stated in captured contract |
| Tweet ID | Replies come from X recent search, covering roughly the last 7 days; requires an X plan with search access | Listing Twitter replies costs 1 credit |
Source-stated platform notes; X/Twitter coverage and plan requirements require implementation-time verification. Credit column records only the stated Twitter/X cost; absence for other platforms is not a verified zero-cost claim.
| Response field | Type | Location | Meaning |
|---|---|---|---|
| success | boolean | Top level | Whether the request succeeded |
| comments | array | Top level | Comments and first-level replies for the post |
| comments[].id | string | Comment object | Comment identifier |
| comments[].text | string | Comment object | Comment text |
| comments[].author | object | Comment object | Author object with id and name |
| comments[].author.id | string | Author object | Author identifier |
| comments[].author.name | string | Author object | Author display name |
| comments[].timestamp | string | Comment object | Comment timestamp in the example format |
| comments[].likeCount | integer | Comment object | Like count for the comment |
| comments[].hidden | boolean | Comment object | Whether the comment is marked hidden |
| comments[].replies | array | Comment object | First-level replies to the comment |
| comments[].replies[].id | string | Reply object | Reply identifier |
| comments[].replies[].text | string | Reply object | Reply text |
| comments[].replies[].author | object | Reply object | Reply author object with id and name |
| comments[].replies[].timestamp | string | Reply object | Reply timestamp in the example format |
| comments[].replies[].likeCount | integer | Reply object | Like count for the reply |
| nextCursor | string or null | Top level | Pass as after for the next page; null means no more pages |
Types inferred from the captured JSON example; source supplied no typed schema. No additional fields invented.
| Check | What to verify | Expected contract behavior |
|---|---|---|
| Missing platform | platform is present and is one of facebook, instagram, threads, linkedin, youtube, or twitter | Request does not identify a supported platform |
| Missing accountId | accountId is present and is the integration ID from list_integrations | Request does not identify the connected account |
| Missing postId | postId is present; YouTube uses the video ID and Twitter/X uses the tweet ID | Request does not identify the post |
| Limit out of range | limit, when supplied, is an integer from 1 to 100; default is 25 when omitted | Values outside 1–100 are outside the documented contract |
| Threads permission | threads_manage_replies is granted | Threads reply listing requires this permission |
| LinkedIn scope | Community Management social-feed scopes are granted; reconnect accounts connected before comment support shipped | Older LinkedIn connections may lack the scopes needed for comments |
| Twitter/X coverage | Replies come from X recent search covering roughly the last 7 days and require an X plan with search access | Older Twitter/X replies may be outside the documented search coverage |
| Twitter/X credit | Listing Twitter replies costs 1 credit | Budget for this cost separately from other platforms |
| Pagination end | nextCursor is null | No more pages; stop sending after |
No error codes invented; the captured contract supplies no status/error schema.
GET {{API_BASE_URL}}/v1/comments?platform=facebook&accountId=YOUR_ACCOUNT_ID&postId=YOUR_POST_ID&limit=25
x-access-key: YOUR_ACCESS_KEY{
"success": true,
"comments": [
{
"id": "123456789",
"text": "An example comment.",
"author": { "id": "987654321", "name": "Jane Doe" },
"timestamp": "2026-07-14T10:00:00.000Z",
"likeCount": 3,
"hidden": false,
"replies": [
{
"id": "111222333",
"text": "An example comment.",
"author": { "id": "444555666", "name": "Your Page" },
"timestamp": "2026-07-14T10:05:00.000Z",
"likeCount": 1
}
]
}
],
"nextCursor": "cursor_abc123"
}GET {{API_BASE_URL}}/v1/comments?platform=facebook&accountId=YOUR_ACCOUNT_ID&postId=YOUR_POST_ID&limit=25&after=cursor_abc123
x-access-key: YOUR_ACCESS_KEYGET /v1/comments
x-access-key: YOUR_ACCESS_KEY