Skip to content

List Comments API

The List Comments API lets you list comments on a post, including first-level replies, across Twitter/X, YouTube, LinkedIn, Threads, Instagram and Facebook destinations linked to your account. Call GET {{API_BASE_URL}}/v1/comments/ with the platform, accountId and postId, then use limit and the Pagination cursor returned as nextCursor to page through results.

List Comments API overview

Use GET {{API_BASE_URL}}/v1/comments/ when you need the comments attached to one item, together with the replies that sit directly beneath them. Six kinds of connected destination are supported, spanning Facebook, Instagram, Threads, LinkedIn, YouTube and Twitter/X, with the account type varying by network. The identifier you supply differs by destination. A YouTube request expects the video identifier in postId, whereas a Twitter request expects the tweet identifier there. On Twitter, reply discovery relies on recent search, a mechanism limited to roughly the past week and available only with an X plan that includes search access. Cost also differs: Twitter reply listing is charged at 1 credit, while the remaining destinations incur no charge for listing. Before calling, confirm the linked destination carries the matching grant: pages_read_user_content on Facebook; instagram_business_manage_comments when Instagram was linked directly, or instagram_manage_comments when linked through Facebook; threads_manage_replies on Threads; the Community Management social-feed scopes on LinkedIn; youtube.force-ssl on YouTube; tweet.read on Twitter.

Authorization

Send the access key in the x-access-key header. The header name is x-access-key and the value is the token placeholder shown in the request example. Error statuses are listed in the status matrix below; the captured source does not assign a specific status to a specific header condition.

Query parameters

Provide platform, accountId and postId on every request. The platform value must be one of facebook, instagram, threads, linkedin, youtube or twitter. accountId is the integration ID of the connected account and postId is the platform post ID to fetch comments for. Optionally set limit to control how many comments are returned and after to continue from a previous page. See the query parameters table for requiredness, types, the platform enum, the limit default and range, and the purpose of after.

Platform postId and permission notes

Match the identifier format to the destination you chose. Facebook, Instagram, Threads and LinkedIn all expect the native identifier of the item on the account named by accountId. YouTube is the exception in form: supply the video identifier. Twitter likewise expects the tweet identifier. Verify the grant for that destination first, and refer to the status matrix for the captured status list without assuming a cause for any particular status.

200 response

A 200 application/json response contains success, comments and nextCursor. Each comment contains id, text, author, timestamp, likeCount and hidden, and may contain replies. Each reply contains id, text, author, timestamp and likeCount. Several fields are nullable, including text, author id and name, timestamp, likeCount and hidden, so client code should handle null values instead of assuming every field is always populated. See the response field map for the full nested structure and nullable types.

Pagination with limit, after and nextCursor

Start with limit set to a value between 1 and 100, or omit limit to use the default of 25. Read nextCursor from the response. If nextCursor is non-null, pass that value as after on the next GET {{API_BASE_URL}}/v1/comments/ request, keeping platform, accountId and postId unchanged. In the captured contract nextCursor is string | null; a null value is the contract representation to check before requesting another page. See the worked pagination example for the exact request sequence.

Error statuses

Handle 200 separately from error statuses. For 400, 401, 402, 403, 404, 429 and 502, the captured body shape is success and message. Do not assume a comments array on error responses. Branch on the HTTP status first, surface message for diagnostics, and only parse comments and nextCursor when the status is 200. See the status matrix for the full list.

Query parameters
ParameterRequiredTypeConstraints / description
platformRequiredstring"facebook" | "instagram" | "threads" | "linkedin" | "youtube" | "twitter" — Platform to fetch comments from.
accountIdRequiredstringIntegration ID of the connected account.
postIdRequiredstringPlatform post ID to fetch comments for.
limitOptionalintegerMax comments to return. Default 25. Range 1 <= value <= 100.
afterOptionalstringPagination cursor from a previous response.

Exact captured query contract for GET {{API_BASE_URL}}/v1/comments/

Platform postId and permission notes
PlatformpostId valueRelevant permission noteCredit / search note
facebookPlatform post IDpages_read_user_contentLists for free
instagramPlatform post IDinstagram_business_manage_comments for direct Instagram Login or instagram_manage_comments for Facebook LoginLists for free
threadsPlatform post IDthreads_manage_repliesLists for free
linkedinPlatform post IDCommunity Management social-feed scopesLists for free
youtubeVideo ID as postIdyoutube.force-sslLists for free
twitterTweet ID as postIdtweet.readListing Twitter replies costs 1 credit; replies found via recent search covering the last ~7 days, needs an X plan with search access

Source contract notes; not independently verified live behavior

200 response fields
FieldRequiredTypeDescription
successRequiredboolean
commentsRequiredarray<object>
comments[].idRequiredstringPlatform comment ID
comments[].textRequiredstring | null
comments[].authorRequiredobject
comments[].author.idRequiredstring | null
comments[].author.nameRequiredstring | null
comments[].timestampRequiredstring | null (date-time)
comments[].likeCountRequirednumber | null
comments[].hiddenRequiredboolean | null
comments[].repliesOptionalarray<object>First-level replies
comments[].replies[].idRequiredstring
comments[].replies[].textRequiredstring | null
comments[].replies[].authorRequiredobject
comments[].replies[].author.idRequiredstring | null
comments[].replies[].author.nameRequiredstring | null
comments[].replies[].timestampRequiredstring | null
comments[].replies[].likeCountRequirednumber | null
nextCursorRequiredstring | nullPass as after in the next request to paginate.

Exact captured 200 response contract

Status matrix
StatusContent typeBody shape
200application/jsonsuccess, comments, nextCursor
400application/jsonsuccess, message
401application/jsonsuccess, message
402application/jsonsuccess, message
403application/jsonsuccess, message
404application/jsonsuccess, message
429application/jsonsuccess, message
502application/jsonsuccess, message

Captured shape only; specific message values not supplied

Frequently asked questions

What is required to list comments on a post?

Send GET {{API_BASE_URL}}/v1/comments/ with platform, accountId and postId as required query parameters, plus the x-access-key header. The response returns comments with first-level replies and a nextCursor for pagination.

What should postId contain for YouTube and Twitter/X?

For YouTube, pass the video ID as postId. For Twitter/X, pass the tweet ID as postId; replies are found via recent search covering the last ~7 days and need an X plan with search access, and listing Twitter replies costs 1 credit while other platforms list for free.

How does pagination work with limit and after?

Set limit between 1 and 100, defaulting to 25 when omitted. When nextCursor is non-null, pass it as the after parameter on the next request to continue pagination.

What response shapes should clients handle?

A 200 response returns success, comments and nextCursor. Error statuses 400, 401, 402, 403, 404, 429 and 502 return the captured success and message shape shown in the error response example.

List comments request example
curl -X GET "{{API_BASE_URL}}/v1/comments/?platform=facebook&accountId=string&postId=string" -H "x-access-key: <token>"
200 success response example
{
  "success": true,
  "comments": [
    {
      "id": "string",
      "text": "string",
      "author": {
        "id": "string",
        "name": "string"
      },
      "timestamp": "2019-08-24T14:15:22Z",
      "likeCount": 0,
      "hidden": true,
      "replies": [
        {
          "id": "string",
          "text": "string",
          "author": {
            "id": "string",
            "name": "string"
          },
          "timestamp": "string",
          "likeCount": 0
        }
      ]
    }
  ],
  "nextCursor": "string"
}
Error response example for 400, 401, 402, 403, 404, 429 and 502
{
  "success": true,
  "message": "string"
}
Worked pagination example with limit, after and nextCursor
curl -X GET "{{API_BASE_URL}}/v1/comments/?platform=facebook&accountId=string&postId=string&limit=25" -H "x-access-key: <token>"
# If the response returns a non-null nextCursor, pass it as after on the next request:
curl -X GET "{{API_BASE_URL}}/v1/comments/?platform=facebook&accountId=string&postId=string&limit=25&after=<nextCursor>" -H "x-access-key: <token>"
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
platform#1platformstring__0YesPlatform to fetch comments from.kind: schemaValueIn; value: "facebook" | "instagram" | "threads" | "linkedin" | "youtube" | "twitter"
accountId#2accountIdstring__0YesIntegration ID of the connected account.
postId#3postIdstring__0YesPlatform post ID to fetch comments for.
limit#4limitinteger__0NoMax comments to return.kind: schemaDefault; value: 25 | kind: schemaRange; value: 1 <= value <= 100
after#5afterstring__0NoPagination cursor from a previous response.
response#6responseobject__0
response#6response.successboolean__1Yes
response#6response.commentsarray<object>__2Yes
response#6response.comments[]object__3
response#6response.comments[].idstring__4YesPlatform comment ID
response#6response.comments[].textstring | null__5Yes
response#6response.comments[].text[variant1]string__5_type:string
response#6response.comments[].text[variant2]null__5_type:null
response#6response.comments[].authorobject__6Yes
response#6response.comments[].author.idstring | null__7Yes
response#6response.comments[].author.id[variant1]string__7_type:string
response#6response.comments[].author.id[variant2]null__7_type:null
response#6response.comments[].author.namestring | null__8Yes
response#6response.comments[].author.name[variant1]string__8_type:string
response#6response.comments[].author.name[variant2]null__8_type:null
response#6response.comments[].timestampstring | null__9Yeskind: schemaFormat; value: date-time
response#6response.comments[].timestamp[variant1]string__9_type:stringkind: schemaFormat; value: date-time
response#6response.comments[].timestamp[variant2]null__9_type:nullkind: schemaFormat; value: date-time
response#6response.comments[].likeCountnumber | null__10Yes
response#6response.comments[].likeCount[variant1]number__10_type:number
response#6response.comments[].likeCount[variant2]null__10_type:null
response#6response.comments[].hiddenboolean | null__11Yes
response#6response.comments[].hidden[variant1]boolean__11_type:boolean
response#6response.comments[].hidden[variant2]null__11_type:null
response#6response.comments[].repliesarray<object>__12No
response#6response.comments[].replies[]object__13
response#6response.comments[].replies[].idstring__14Yes
response#6response.comments[].replies[].textstring | null__15Yes
response#6response.comments[].replies[].text[variant1]string__15_type:string
response#6response.comments[].replies[].text[variant2]null__15_type:null
response#6response.comments[].replies[].authorobject__16Yes
response#6response.comments[].replies[].author.idstring | null__17Yes
response#6response.comments[].replies[].author.id[variant1]string__17_type:string
response#6response.comments[].replies[].author.id[variant2]null__17_type:null
response#6response.comments[].replies[].author.namestring | null__18Yes
response#6response.comments[].replies[].author.name[variant1]string__18_type:string
response#6response.comments[].replies[].author.name[variant2]null__18_type:null
response#6response.comments[].replies[].timestampstring | null__19Yes
response#6response.comments[].replies[].timestamp[variant1]string__19_type:string
response#6response.comments[].replies[].timestamp[variant2]null__19_type:null
response#6response.comments[].replies[].likeCountnumber | null__20Yes
response#6response.comments[].replies[].likeCount[variant1]number__20_type:number
response#6response.comments[].replies[].likeCount[variant2]null__20_type:null
response#6response.nextCursorstring | null__21YesPass as after in the next request to paginate.
response#6response.nextCursor[variant1]string__21_type:stringPass as after in the next request to paginate.
response#6response.nextCursor[variant2]null__21_type:nullPass as after in the next request to paginate.
response#7responseobject__0
response#7response.successboolean__1Yes
response#7response.messagestring__2Yes