API Documentation

TikTok Comment API

Collect video comments and replies with background tasks.

Test API

Collect one main-comment page or all available comments, optionally including every available reply to the selected comments.

Test TikTok Comment API →

Submit a task

POST https://api.goanyapi.com/api/v1/tiktok-comments/tasks

Authenticate with Authorization: Bearer YOUR_API_KEY and send a JSON body. HTTP 202 means acceptance, not completed collection. Save data.task_id and query it using the separate endpoint below.

Input parameters

ParameterTypeLocationRequiredConstraints / defaultDescription
AuthorizationstringHeaderYesBearer YOUR_API_KEYAPI key for the current account.
Content-TypestringHeaderRecommendedapplication/jsonUse when sending the JSON request body.
video_urlstringJSON bodyYes—Full HTTPS TikTok video URL, such as https://www.tiktok.com/@spidey.glow/video/7686957509826923808?is_from_webapp=1&sender_device=pc. Query parameters, fragments and a trailing slash are removed before collection. Short links are not supported.
modestringJSON bodyNopage / all; default: pagepage collects one main-comment page; all automatically collects every available page.
cursorstringJSON bodyNopattern: ^[0-9]+$Main-comment cursor, allowed only in page mode. Omit for the first page; use collection.next_cursor for subsequent pages.
include_repliesbooleanJSON bodyNodefault: falseCollect all available replies to the selected main comments. Main comments and replies both count toward billing.

Request example

POST /api/v1/tiktok-comments/tasks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{"video_url":"https://www.tiktok.com/@user/video/7702491752548027656","mode":"page","cursor":"0","include_replies":true}

video_url is required and must be a full HTTPS TikTok video URL; short links are unsupported. Sharing query parameters (such as ?is_from_webapp=1&sender_device=pc), fragments and a trailing slash are accepted and removed before collection. These two URLs locate the same video:

https://www.tiktok.com/@spidey.glow/video/7686957509826923808?is_from_webapp=1&sender_device=pc
https://www.tiktok.com/@spidey.glow/video/7686957509826923808

mode is page (default) or all. cursor is an optional numeric string, allowed only with page; omit it for the first page, then use collection.next_cursor. include_replies is a boolean, default false. Both main-comment and reply requests use fixed batches of 40; count is not a public parameter. Page mode collects one main-comment page and, when requested, all available replies to those comments. All mode follows every available page. No user quantity cap is required.

Returns HTTP 202 with data.task_id and data.status=queued. Submission does not itself charge credits, but requires enough balance for the first billing unit. Each submission creates an independent task.

Output parameters

The submission returns task metadata. Counts and charged credits start at zero, and items starts empty. Do not treat acceptance as the completed collection result.

FieldTypeDescription
codestringok when the API request succeeds; task state is in data.status.
messagestringok for a successful request.
data.task_idstringTask ID: ttc_ followed by 32 hexadecimal characters.
data.statusstringqueued: accepted, not completed.
data.created_atstring (ISO 8601)Task creation time in UTC.
data.expires_atstring (ISO 8601)Retention deadline in UTC, 30 days after submission.
data.counts.commentsintegerZero at submission.
data.counts.repliesintegerZero at submission.
data.counts.totalintegerZero at submission.
data.billing.credits_usednumberCredits charged so far; zero at submission.
data.billing.records_per_unitintegerRecords per billing unit, counting main comments and replies together.
data.billing.credits_per_unitnumberConfigured rate fixed when the task is created.
data.collection.completebooleanWhether the selected scope is complete; true for succeeded.
data.collection.has_morebooleanWhether main-comment collection has another page; distinct from saved-result pagination.
data.collection.next_cursorstring | nullNext main-comment cursor in page mode; null for all mode or no next page.
data.collection.stop_reasonstring | nullNormally null; insufficient_credits or collection_failed when collection stops early.
data.itemsarrayEmpty at submission; retrieve results through the query endpoint.
data.results.has_morebooleanWhether more saved results follow; this does not indicate task completion.
data.results.next_cursorstring | nullresult_cursor for the next query; null when no further saved records exist.

Response example (HTTP 202)

This structural example is not a real task. For readability it omits created_at, expires_at, billing.records_per_unit and billing.credits_per_unit, which are present in actual responses. Rates come from configuration and are not hardcoded in examples.

{  "code": "ok",  "message": "ok",  "data": {    "task_id": "ttc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",    "status": "queued",    "counts": {      "comments": 0,      "replies": 0,      "total": 0    },    "billing": {      "credits_used": 0    },    "collection": {      "complete": false,      "has_more": true,      "next_cursor": null,      "stop_reason": null    },    "items": [],    "results": {      "has_more": false,      "next_cursor": null    }  }}

Query status and saved results

Catalog ID: tiktok-comments-task; MCP tool: goanyapi_tiktok_comments_task.

GET https://api.goanyapi.com/api/v1/tiktok-comments/tasks/{task_id}

Authenticate with Authorization: Bearer YOUR_API_KEY. There is no request body: put the task ID in the path and saved-result pagination in query parameters.

Input parameters

ParameterTypeLocationRequiredConstraints / defaultDescription
AuthorizationstringHeaderYesBearer YOUR_API_KEYAPI key for the current account.
task_idstringPathYespattern: ^ttc_[a-f0-9]{32}$Task ID returned by the submit tool, belonging to the current account.
result_cursorstringQueryNopattern: ^[0-9]+$Use results.next_cursor to read the next saved result page; omit for the first page.
limitintegerQueryNo1–100; default: 100Saved records per response; does not affect collection or charges.

Request example

GET /api/v1/tiktok-comments/tasks/{task_id}?limit=100
Authorization: Bearer YOUR_API_KEY

Poll every 5 seconds. limit is an integer from 1 to 100 (default 100); result_cursor is an optional numeric string taken from results.next_cursor. This paginates saved results, independently of the collection cursor. Queries and repeated downloads are free.

Collection runs in bounded background batches. Continue polling while queued or running to wake subsequent batches; without further queries, a long task may remain pending. Closing the page does not delete saved results. Query the same task ID later to continue processing.

Statuses: queued, running, succeeded, partial, failed. A partial task exposes its stop reason (insufficient_credits or collection_failed) and retains paid results. counts.comments, counts.replies, and counts.total count saved unique records. billing.credits_used reports charges; collection.complete indicates whether the selected scope completed. Results include original public comment fields, type=comment|reply and parent_comment_id; null, empty and missing business fields are preserved. IDs and cursors are strings.

Output parameters

HTTP 200 means the query succeeded. Use data.status and data.collection.complete to determine completion. items contains only this result page; counts.total covers all saved records in the task, so their sizes can differ.

FieldTypeDescription
codestringok when the API request succeeds; task state is in data.status.
messagestringok for a successful request.
data.task_idstringTask ID: ttc_ followed by 32 hexadecimal characters.
data.statusstringqueued / running / succeeded / partial / failed; see task states.
data.created_atstring (ISO 8601)Task creation time in UTC.
data.expires_atstring (ISO 8601)Retention deadline in UTC, 30 days after submission.
data.counts.commentsintegerSaved unique main comments.
data.counts.repliesintegerSaved unique replies.
data.counts.totalintegerTotal saved records: comments plus replies.
data.billing.credits_usednumberCredits charged so far; zero at submission.
data.billing.records_per_unitintegerRecords per billing unit, counting main comments and replies together.
data.billing.credits_per_unitnumberConfigured rate fixed when the task is created.
data.collection.completebooleanWhether the selected scope is complete; true for succeeded.
data.collection.has_morebooleanWhether main-comment collection has another page; distinct from saved-result pagination.
data.collection.next_cursorstring | nullNext main-comment cursor in page mode; null for all mode or no next page.
data.collection.stop_reasonstring | nullNormally null; insufficient_credits or collection_failed when collection stops early.
data.itemsarraySaved records for this result page; [] when none are saved yet.
data.results.has_morebooleanWhether more saved results follow; this does not indicate task completion.
data.results.next_cursorstring | nullresult_cursor for the next query; null when no further saved records exist.

Comment record fields

Except id, type and parent_comment_id, business fields may be absent, null or empty and are preserved as returned. Types below describe the usual representation.

FieldTypeDescription
data.items[].idstringComment or reply ID.
data.items[].typestringcomment for a main comment; reply for a reply.
data.items[].parent_comment_idstring | nullParent comment ID for a reply; null for a main comment.
data.items[].userAvatarstring | nullUser avatar URL.
data.items[].userNamestring | nullUser name.
data.items[].contentstring | nullComment text.
data.items[].createTimenumber | nullCreation time, normally a Unix timestamp in seconds.
data.items[].likeCountnumber | nullLike count.
data.items[].replyCountnumber | nullReported reply count, not the number of replies included on this result page.

Response example (HTTP 200)

This structural example contains one main comment and is not a real task. It omits created_at, expires_at and billing. The table above defines the complete fields; actual tasks return billing information.

{  "code": "ok",  "message": "ok",  "data": {    "task_id": "ttc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",    "status": "succeeded",    "counts": {      "comments": 1,      "replies": 0,      "total": 1    },    "collection": {      "complete": true,      "has_more": false,      "next_cursor": null,      "stop_reason": null    },    "items": [      {        "id": "7702501823814419213",        "type": "comment",        "parent_comment_id": null,        "userName": "ilikemusicabit",        "content": "What if I want them to watch",        "createTime": 1793378501,        "likeCount": 340012,        "replyCount": 709      }    ],    "results": {      "has_more": false,      "next_cursor": null    }  }}

Task states and the two cursors

StateMeaningNext step
queuedAwaiting processingContinue polling every 5 seconds
runningCollecting; some results may already existContinue polling every 5 seconds
succeededThe selected scope is completeStop polling; read remaining saved-result pages
partialStopped early with saved results retainedStop polling, inspect the stop reason and resume if needed
failedCollection failedStop polling, inspect the stop reason and retry through resume if needed

Use collection.next_cursor to submit collection of another main-comment page in page mode. Use results.next_cursor to query another saved-result page of the same task. Do not interchange them. results.has_more=false does not mean collection is complete: queued or running tasks may save more records later.

Resume

Catalog ID: tiktok-comments-resume; MCP tool: goanyapi_tiktok_comments_resume.

POST https://api.goanyapi.com/api/v1/tiktok-comments/tasks/{task_id}/resume
POST /api/v1/tiktok-comments/tasks/{task_id}/resume
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{}

Resume an unexpired partial or failed task. Existing results and counters remain; new records continue the task's original billing rate. Resume itself is free. Expired tasks return 410; another user's task returns 404.

The task_id path parameter is the same as for querying. Send {} as the JSON body. HTTP 202 returns the submission response fields while preserving the task ID, saved results, counts and charges, with the task queued again. Continue through the query endpoint.

HTTP errors

400: invalid JSON, video URL, mode, cursor, pagination or task ID; 401: no valid API key; 402: insufficient balance to create a task; 404: task missing or owned by another account; 409: task cannot currently resume; 410: task expired; 429: rate limit. Insufficient balance during collection and collection failures appear in task status and collection.stop_reason, with saved results retained.

500 indicates an internal service error. Error bodies contain string fields code and message, optionally details, and do not contain the successful data object.

{
  "code": "invalid_params",
  "message": "Provide valid TikTok comment parameters"
}

This example accompanies HTTP 400 for invalid submission parameters. A query can return HTTP 200 for a partial or failed task; inspect data.collection.stop_reason instead of treating HTTP success as successful collection.

Billing and retention

1 credit per 100 records (rounded up)

Main comments and replies count together. Billing units are rounded up per 100 unique saved records per task, charged progressively and atomically with result persistence. Zero records cost nothing. Retries and repeated records within the task are not charged again. Insufficient balance stops collection without discarding paid results. A partial collection is charged only for delivered saved records. Results remain available until expires_at, 30 days after submission; expiry also disables resume. Available data can differ from the video page's displayed total.