TikTok Comment API
Collect video comments and replies with background tasks.
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/tasksAuthenticate 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
| Parameter | Type | Location | Required | Constraints / default | Description |
|---|---|---|---|---|---|
Authorization | string | Header | Yes | Bearer YOUR_API_KEY | API key for the current account. |
Content-Type | string | Header | Recommended | application/json | Use when sending the JSON request body. |
video_url | string | JSON body | Yes | — | 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. |
mode | string | JSON body | No | page / all; default: page | page collects one main-comment page; all automatically collects every available page. |
cursor | string | JSON body | No | pattern: ^[0-9]+$ | Main-comment cursor, allowed only in page mode. Omit for the first page; use collection.next_cursor for subsequent pages. |
include_replies | boolean | JSON body | No | default: false | Collect 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/7686957509826923808mode 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.
| Field | Type | Description |
|---|---|---|
code | string | ok when the API request succeeds; task state is in data.status. |
message | string | ok for a successful request. |
data.task_id | string | Task ID: ttc_ followed by 32 hexadecimal characters. |
data.status | string | queued: accepted, not completed. |
data.created_at | string (ISO 8601) | Task creation time in UTC. |
data.expires_at | string (ISO 8601) | Retention deadline in UTC, 30 days after submission. |
data.counts.comments | integer | Zero at submission. |
data.counts.replies | integer | Zero at submission. |
data.counts.total | integer | Zero at submission. |
data.billing.credits_used | number | Credits charged so far; zero at submission. |
data.billing.records_per_unit | integer | Records per billing unit, counting main comments and replies together. |
data.billing.credits_per_unit | number | Configured rate fixed when the task is created. |
data.collection.complete | boolean | Whether the selected scope is complete; true for succeeded. |
data.collection.has_more | boolean | Whether main-comment collection has another page; distinct from saved-result pagination. |
data.collection.next_cursor | string | null | Next main-comment cursor in page mode; null for all mode or no next page. |
data.collection.stop_reason | string | null | Normally null; insufficient_credits or collection_failed when collection stops early. |
data.items | array | Empty at submission; retrieve results through the query endpoint. |
data.results.has_more | boolean | Whether more saved results follow; this does not indicate task completion. |
data.results.next_cursor | string | null | result_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
| Parameter | Type | Location | Required | Constraints / default | Description |
|---|---|---|---|---|---|
Authorization | string | Header | Yes | Bearer YOUR_API_KEY | API key for the current account. |
task_id | string | Path | Yes | pattern: ^ttc_[a-f0-9]{32}$ | Task ID returned by the submit tool, belonging to the current account. |
result_cursor | string | Query | No | pattern: ^[0-9]+$ | Use results.next_cursor to read the next saved result page; omit for the first page. |
limit | integer | Query | No | 1–100; default: 100 | Saved 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_KEYPoll 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.
| Field | Type | Description |
|---|---|---|
code | string | ok when the API request succeeds; task state is in data.status. |
message | string | ok for a successful request. |
data.task_id | string | Task ID: ttc_ followed by 32 hexadecimal characters. |
data.status | string | queued / running / succeeded / partial / failed; see task states. |
data.created_at | string (ISO 8601) | Task creation time in UTC. |
data.expires_at | string (ISO 8601) | Retention deadline in UTC, 30 days after submission. |
data.counts.comments | integer | Saved unique main comments. |
data.counts.replies | integer | Saved unique replies. |
data.counts.total | integer | Total saved records: comments plus replies. |
data.billing.credits_used | number | Credits charged so far; zero at submission. |
data.billing.records_per_unit | integer | Records per billing unit, counting main comments and replies together. |
data.billing.credits_per_unit | number | Configured rate fixed when the task is created. |
data.collection.complete | boolean | Whether the selected scope is complete; true for succeeded. |
data.collection.has_more | boolean | Whether main-comment collection has another page; distinct from saved-result pagination. |
data.collection.next_cursor | string | null | Next main-comment cursor in page mode; null for all mode or no next page. |
data.collection.stop_reason | string | null | Normally null; insufficient_credits or collection_failed when collection stops early. |
data.items | array | Saved records for this result page; [] when none are saved yet. |
data.results.has_more | boolean | Whether more saved results follow; this does not indicate task completion. |
data.results.next_cursor | string | null | result_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.
| Field | Type | Description |
|---|---|---|
data.items[].id | string | Comment or reply ID. |
data.items[].type | string | comment for a main comment; reply for a reply. |
data.items[].parent_comment_id | string | null | Parent comment ID for a reply; null for a main comment. |
data.items[].userAvatar | string | null | User avatar URL. |
data.items[].userName | string | null | User name. |
data.items[].content | string | null | Comment text. |
data.items[].createTime | number | null | Creation time, normally a Unix timestamp in seconds. |
data.items[].likeCount | number | null | Like count. |
data.items[].replyCount | number | null | Reported 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
| State | Meaning | Next step |
|---|---|---|
queued | Awaiting processing | Continue polling every 5 seconds |
running | Collecting; some results may already exist | Continue polling every 5 seconds |
succeeded | The selected scope is complete | Stop polling; read remaining saved-result pages |
partial | Stopped early with saved results retained | Stop polling, inspect the stop reason and resume if needed |
failed | Collection failed | Stop 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}/resumePOST /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.