> ## Documentation Index > Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # TikTok comment lookup > Look up a public TikTok root comment or reply, or search by case-insensitive author handle or text snippet. Canonical and m.tiktok.com video URLs accept numeric or base64 comment IDs; shortlinks are not yet resolved. Flat 2 credits, or 6 with deep_scan=true. Scans are bounded to 3/9 source pages of up to 30 rows, within 50 seconds. A provider-list end without a match returns an uncharged 404; an unfinished bounded scan returns uncharged 503 LOOKUP_SCAN_LIMIT. Source-list completion is not proof that every TikTok comment is exposed. Signed position hints expire after 10 minutes and probe fresh data. Costs **2 credits** per successful lookup, or **6 credits** with `deep_scan=true`. Errors, cache hits, and successful idempotent replays cost zero. Use `X-Max-Credits: 2` (or `6` for a deep scan) to cap the charge. A position hint reduces source work, not the flat price. Pass a `comment_url`, or `post_url` with `comment_id`. For a reply, also provide `parent_comment_id`. Canonical video links and `m.tiktok.com/v/{id}.html` links accept numeric or base64-encoded `comment_id`, `share_comment_id`, or `cid` values. Other URL query parameters and `vm.tiktok.com` / `/t/` shortlinks are not yet supported and return an uncharged 422. Alternatively, use `post_url` with **either** `author_username` **or** `text_contains`. Both searches are case-insensitive. Search returns `data.matches` with up to `max` comments (1–20, default 5). Exact lookups return `data.comment`. Each comment preserves the source identity, author, text, current like/reply counts, timestamp, pinned/liked flags and image URLs; unavailable optional values remain null. The video ID is checked against every returned comment. The profile handle supplied in the video URL is not proof of the video's author. Standard scans inspect at most 3 pages; deep scans inspect at most 9. Each page contains up to 30 source comments, and both modes have a 50-second deadline. `lookup.scan_complete` means the provider ended its available list. It does **not** certify that every TikTok comment or reply was exposed. Search may return fewer than `max` matches with `scan_complete=false`. An available list ending without a match returns **404 `RESOURCE_NOT_FOUND`**. A scan that reaches its limit without finding a match returns **503 `LOOKUP_SCAN_LIMIT`**, never a false not-found claim. Provider errors, malformed identity, and budget exhaustion fail without charging. Exact lookups return `lookup.position_hint`; search matches each include their own hint. Hints are signed, bound to the same source provider and video/comment/parent, and expire after 10 minutes. Passing one probes its saved source cursor and reads the current comment. A stale hint restarts at page one within the same scan budget. It is not a stored comment snapshot. Successful responses may be cached for five minutes; use `Cache-Control: no-cache` when you need a new source read. Sources: [TikHub public app API](https://api.tikhub.io/) with [ScrapeBadger TikTok comments](https://docs.scrapebadger.com/api-reference/endpoint/tiktok/get-comments) and [replies](https://docs.scrapebadger.com/api-reference/endpoint/tiktok/get-comment-replies), as a fallback using the US region. Availability and ordering can differ between sources. Hints pin the original source and are never sent to the fallback. TikHub does not establish the verification badge, so that field remains null. Provider trial balances and verification ceilings are finite; this is not a guarantee of continuously funded service. Shortlink resolution remains a parity gap. ## OpenAPI ````yaml GET /tiktok/comment openapi: 3.1.0 info: title: SocialQuery API version: '2026-10-09' description: >- Documented requests for public-source records. Inspect accepted inputs and credit amounts, then verify the selected operation before integrating preview coverage. servers: - url: https://socialquery.dev/v1 security: - apiKey: [] paths: /tiktok/comment: get: tags: - TikTok summary: Look up or search public TikTok comments description: >- Look up a public TikTok root comment or reply, or search by case-insensitive author handle or text snippet. Canonical and m.tiktok.com video URLs accept numeric or base64 comment IDs; shortlinks are not yet resolved. Flat 2 credits, or 6 with deep_scan=true. Scans are bounded to 3/9 source pages of up to 30 rows, within 50 seconds. A provider-list end without a match returns an uncharged 404; an unfinished bounded scan returns uncharged 503 LOOKUP_SCAN_LIMIT. Source-list completion is not proof that every TikTok comment is exposed. Signed position hints expire after 10 minutes and probe fresh data. operationId: get_tiktok_comment parameters: - name: comment_url in: query required: false example: >- https://www.tiktok.com/@daviddobrik/video/7166718514751933739?comment_id=7166719450585531142 schema: type: string description: >- Canonical https://www.tiktok.com/@handle/video/id URL or https://m.tiktok.com/v/id.html URL, with comment_id, share_comment_id or cid. IDs may be numeric or base64 encoded. No other query fields, fragments or shortlinks. Mutually exclusive with post_url and comment_id. - name: post_url in: query required: false schema: type: string description: >- Canonical TikTok video URL; combine with comment_id or an author/text search. One of comment_url or post_url is required. - name: comment_id in: query required: false schema: type: string description: >- Numeric comment ID. Requires post_url. For a reply also supply parent_comment_id. - name: parent_comment_id in: query required: false schema: type: string description: >- Numeric parent ID when looking up a reply. It must differ from the target comment ID. - name: author_username in: query required: false schema: type: string description: >- Case-insensitive handle, optionally prefixed with @. Mutually exclusive with text_contains and any comment ID. - name: text_contains in: query required: false schema: type: string description: >- Case-insensitive snippet of 1–500 characters. Mutually exclusive with author_username and any comment ID. - name: deep_scan in: query required: false schema: type: boolean default: false description: >- Increase the scan ceiling from 3 to 9 pages. Successful calls cost 6 credits instead of 2; both modes use a 50-second deadline. - name: position_hint in: query required: false schema: type: string description: >- Signed opaque hint from a previous exact lookup or search match; valid for 10 minutes and bound to the same source provider, video, comment and parent. A stale location restarts at page one within the same page budget. Does not reduce the flat credit price. - name: max in: query required: false schema: type: integer minimum: 1 maximum: 20 default: 5 description: >- Maximum search matches, 1–20, default 5. Not accepted for a comment-ID lookup. - name: Cache-Control in: header required: false example: no-cache schema: type: string - name: Idempotency-Key in: header required: false example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c schema: type: string - name: X-Max-Credits in: header required: false description: >- Optional nonnegative integer cap on the maximum request hold. A live request whose hold exceeds this cap returns 422 CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the requested limit; cache hits and successful idempotent replays cost zero. schema: type: integer minimum: 0 responses: '200': description: >- Look up a public TikTok root comment or reply, or search by case-insensitive author handle or text snippet. Canonical and m.tiktok.com video URLs accept numeric or base64 comment IDs; shortlinks are not yet resolved. Flat 2 credits, or 6 with deep_scan=true. Scans are bounded to 3/9 source pages of up to 30 rows, within 50 seconds. A provider-list end without a match returns an uncharged 404; an unfinished bounded scan returns uncharged 503 LOOKUP_SCAN_LIMIT. Source-list completion is not proof that every TikTok comment is exposed. Signed position hints expire after 10 minutes and probe fresh data. content: application/json: schema: allOf: - $ref: '#/components/schemas/SocialQueryResponse' - type: object properties: data: oneOf: - type: object properties: lookup: type: object properties: post_id: type: string parent_comment_id: type: - string - 'null' position_hint: type: - string - 'null' pages_scanned: type: integer minimum: 1 maximum: 9 comments_scanned: type: integer minimum: 0 scan_complete: type: boolean page_limit: type: integer enum: - 3 - 9 post_comment_count: type: 'null' required: - post_id - parent_comment_id - position_hint - pages_scanned - comments_scanned - scan_complete - page_limit - post_comment_count additionalProperties: false source: type: string coverage_note: type: string comment: type: object properties: id: type: string post_id: type: string parent_id: type: - string - 'null' url: type: string text: type: string author: type: object properties: id: type: string username: type: string display_name: type: - string - 'null' avatar_url: type: - string - 'null' verified: type: - boolean - 'null' required: - id - username - display_name - avatar_url - verified additionalProperties: false likes: type: - integer - 'null' minimum: 0 reply_count: type: - integer - 'null' minimum: 0 published_at: type: string format: date-time flags: type: object properties: pinned: type: - boolean - 'null' liked_by_author: type: - boolean - 'null' required: - pinned - liked_by_author additionalProperties: false ext: type: object properties: language: type: - string - 'null' image_urls: type: array items: type: - string - 'null' maxItems: 30 required: - language - image_urls additionalProperties: false required: - id - post_id - parent_id - url - text - author - likes - reply_count - published_at - flags - ext additionalProperties: false required: - lookup - source - coverage_note - comment additionalProperties: false - type: object properties: lookup: type: object properties: post_id: type: string parent_comment_id: type: - string - 'null' position_hint: type: - string - 'null' pages_scanned: type: integer minimum: 1 maximum: 9 comments_scanned: type: integer minimum: 0 scan_complete: type: boolean page_limit: type: integer enum: - 3 - 9 post_comment_count: type: 'null' required: - post_id - parent_comment_id - position_hint - pages_scanned - comments_scanned - scan_complete - page_limit - post_comment_count additionalProperties: false source: type: string coverage_note: type: string matches: type: array minItems: 1 maxItems: 20 items: type: object properties: comment: type: object properties: id: type: string post_id: type: string parent_id: type: - string - 'null' url: type: string text: type: string author: type: object properties: id: type: string username: type: string display_name: type: - string - 'null' avatar_url: type: - string - 'null' verified: type: - boolean - 'null' required: - id - username - display_name - avatar_url - verified additionalProperties: false likes: type: - integer - 'null' minimum: 0 reply_count: type: - integer - 'null' minimum: 0 published_at: type: string format: date-time flags: type: object properties: pinned: type: - boolean - 'null' liked_by_author: type: - boolean - 'null' required: - pinned - liked_by_author additionalProperties: false ext: type: object properties: language: type: - string - 'null' image_urls: type: array items: type: - string - 'null' maxItems: 30 required: - language - image_urls additionalProperties: false required: - id - post_id - parent_id - url - text - author - likes - reply_count - published_at - flags - ext additionalProperties: false position_hint: type: string required: - comment - position_hint additionalProperties: false required: - lookup - source - coverage_note - matches additionalProperties: false required: - data '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '402': $ref: '#/components/responses/Error402' '403': $ref: '#/components/responses/Error403' '404': $ref: '#/components/responses/Error404' '405': $ref: '#/components/responses/Error405' '409': $ref: '#/components/responses/Error409' '422': $ref: '#/components/responses/Error422' '429': $ref: '#/components/responses/Error429' '500': $ref: '#/components/responses/Error500' '502': $ref: '#/components/responses/Error502' '503': $ref: '#/components/responses/Error503' '504': $ref: '#/components/responses/Error504' components: schemas: SocialQueryResponse: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - data properties: success: type: boolean const: true platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean data: type: object additionalProperties: true description: >- The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null. SocialQueryError: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - error properties: success: type: boolean const: false platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean error: type: object required: - code - type - message - status - doc_url properties: code: type: string type: type: string message: type: string status: type: integer doc_url: type: string format: uri responses: Error400: description: Upstream rejected the request. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error401: description: Missing, expired, invalid, or revoked API key. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error402: description: Insufficient SocialQuery credits. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error403: description: Key scope or provider policy denied access. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error404: description: Endpoint or upstream resource not found. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error405: description: HTTP method is not supported. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error409: description: Idempotency conflict or request in progress. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error422: description: Invalid parameters. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error429: description: Request limit reached. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error500: description: Request processing failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error502: description: Upstream service failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error503: description: Provider or required service is unavailable. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error504: description: Upstream service timed out. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.