Skip to content

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.

Query parameters field map
ParameterTypeRequiredDescription
platformstringYesfacebook, instagram, threads, linkedin, youtube, or twitter
accountIdstringYesIntegration ID from list_integrations
postIdstringYesPlatform post ID; for YouTube pass the video ID, for Twitter/X pass the tweet ID
limitintegerNoMax comments to return (1–100, default 25)
afterstringNoPagination cursor from a previous response; pass the previous nextCursor value

Source contract preserved exactly; origin modularized as {{API_BASE_URL}}.

Platform decision table
PlatformpostId meaningPermission or coverage noteCredit note
facebookPlatform post IDConnected Facebook PageNo per-call credit exception stated in captured contract
instagramPlatform post IDConnected Instagram Business accountNo per-call credit exception stated in captured contract
threadsPlatform post IDRequires threads_manage_repliesNo per-call credit exception stated in captured contract
linkedinPlatform post IDRequires Community Management social-feed scopes; accounts connected before comment support shipped must reconnect to grant themNo per-call credit exception stated in captured contract
youtubeVideo IDConnected YouTube videoNo per-call credit exception stated in captured contract
twitterTweet IDReplies come from X recent search, covering roughly the last 7 days; requires an X plan with search accessListing 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 map
Response fieldTypeLocationMeaning
successbooleanTop levelWhether the request succeeded
commentsarrayTop levelComments and first-level replies for the post
comments[].idstringComment objectComment identifier
comments[].textstringComment objectComment text
comments[].authorobjectComment objectAuthor object with id and name
comments[].author.idstringAuthor objectAuthor identifier
comments[].author.namestringAuthor objectAuthor display name
comments[].timestampstringComment objectComment timestamp in the example format
comments[].likeCountintegerComment objectLike count for the comment
comments[].hiddenbooleanComment objectWhether the comment is marked hidden
comments[].repliesarrayComment objectFirst-level replies to the comment
comments[].replies[].idstringReply objectReply identifier
comments[].replies[].textstringReply objectReply text
comments[].replies[].authorobjectReply objectReply author object with id and name
comments[].replies[].timestampstringReply objectReply timestamp in the example format
comments[].replies[].likeCountintegerReply objectLike count for the reply
nextCursorstring or nullTop levelPass 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.

Failure and edge checks
CheckWhat to verifyExpected contract behavior
Missing platformplatform is present and is one of facebook, instagram, threads, linkedin, youtube, or twitterRequest does not identify a supported platform
Missing accountIdaccountId is present and is the integration ID from list_integrationsRequest does not identify the connected account
Missing postIdpostId is present; YouTube uses the video ID and Twitter/X uses the tweet IDRequest does not identify the post
Limit out of rangelimit, when supplied, is an integer from 1 to 100; default is 25 when omittedValues outside 1–100 are outside the documented contract
Threads permissionthreads_manage_replies is grantedThreads reply listing requires this permission
LinkedIn scopeCommunity Management social-feed scopes are granted; reconnect accounts connected before comment support shippedOlder LinkedIn connections may lack the scopes needed for comments
Twitter/X coverageReplies come from X recent search covering roughly the last 7 days and require an X plan with search accessOlder Twitter/X replies may be outside the documented search coverage
Twitter/X creditListing Twitter replies costs 1 creditBudget for this cost separately from other platforms
Pagination endnextCursor is nullNo more pages; stop sending after

No error codes invented; the captured contract supplies no status/error schema.

List comments request example
GET {{API_BASE_URL}}/v1/comments?platform=facebook&accountId=YOUR_ACCOUNT_ID&postId=YOUR_POST_ID&limit=25
x-access-key: YOUR_ACCESS_KEY
List comments response example
{
	"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"
}
Pagination request using nextCursor as after
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_KEY
Contract example 1
GET /v1/comments
x-access-key: YOUR_ACCESS_KEY