openapi_v2_tiktok_videos_search
Tiktok Videos Search
Search daily-updated TikTok videos by engagement, creator, and commerce signals.
Filter by play and like counts, interaction rate, creator follower count, publish date, whether the video carries a shoppable product, and the product's category (by id or path). Each video also returns the primary product's category id and path. Data is from the latest daily video collection within the fallback window. Interaction rate is (likes + comments + shares + saves) / plays, as a decimal; it is computed per video, so filtering by it narrows the result set but does not reduce query time. Related: /tiktok/creators/search and /tiktok/products/search.
Responses:
200: Successful Response (Success Response) Content-Type: application/json
Example Response:
{
"success": true,
"meta": {
"requestId": "Requestid",
"timestamp": "Timestamp"
}
}Output Schema:
{
"properties": {
"success": {
"type": "boolean",
"title": "Success",
"description": "Whether the request was successful",
"default": true
},
"data": {
"title": "Data",
"description": "Response data payload"
},
"error": {
"description": "Error details if request failed"
},
"meta": {
"description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
"properties": {
"requestId": {
"type": "string",
"title": "Requestid",
"description": "Unique request identifier"
},
"timestamp": {
"type": "string",
"title": "Timestamp",
"description": "Response timestamp in ISO 8601 format"
},
"total": {
"title": "Total",
"description": "Total number of records"
},
"page": {
"title": "Page",
"description": "Current page number"
},
"pageSize": {
"title": "Pagesize",
"description": "Number of records per page"
},
"totalPages": {
"title": "Totalpages",
"description": "Total number of pages"
},
"creditsRemaining": {
"title": "Creditsremaining",
"description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
},
"creditsConsumed": {
"title": "Creditsconsumed",
"description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
},
"creditsRemainingExact": {
"title": "Creditsremainingexact",
"description": "Remaining API credits, precise to 1 decimal place"
},
"creditsConsumedExact": {
"title": "Creditsconsumedexact",
"description": "Credits consumed by this request, precise to 1 decimal place"
},
"tokensUsage": {
"description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
}
},
"type": "object",
"required": [
"requestId",
"timestamp"
],
"title": "ResponseMeta"
}
},
"type": "object",
"required": [
"meta"
],
"title": "OpenApiResponse[list[TikTokVideo]]",
"examples": []
}422: Validation Error Content-Type: application/json
Example Response:
{
"detail": [
{
"loc": [],
"msg": "Message",
"type": "Error Type",
"ctx": {}
}
]
}Output Schema:
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number. | |
| isAigc | No | Filter by AI-generated-content status. true = only AIGC videos; false = only confirmed non-AIGC (unknown excluded). Omit to return all. Unknown status is not directly filterable — a result with no isAigc field has unknown status. | |
| sortBy | No | Sort field for video search. | playCount |
| videoId | No | Exact TikTok video ID to look up. | |
| pageSize | No | Page size, 1–100; values above 20 are served as 20. Default 20. | |
| sortOrder | No | Sort direction. Default desc. | desc |
| categoryId | No | TikTok category ID — matches videos whose primary product anchor category has this id at any of the 7 hierarchy levels. | |
| hasProduct | No | Filter by whether the video carries a shoppable product. True: the video has a TikTok Shop product anchor; False: it has none. Omit to include both. | |
| categoryPath | No | Category path names, root → leaf, e.g. ['Home Improvement', 'Bathroom Fixtures']. Subtree match: the video's first N category level names must equal the N supplied segments in order; deeper levels (if any) are unconstrained. A partial path matches the whole subtree below it; supply the full leaf path to narrow to that single node. Must contain 1 to 7 segments (TikTok's max category depth) — deeper paths are rejected. | |
| diggCountMax | No | Maximum like count. | |
| diggCountMin | No | Minimum like count. | |
| playCountMax | No | Maximum play (view) count. | |
| playCountMin | No | Minimum play (view) count. | |
| shareCountMax | No | Maximum share count. | |
| shareCountMin | No | Minimum share count. | |
| publishedAtMax | No | Latest publish date (inclusive), as YYYY-MM-DD in UTC, e.g. 2026-06-30. | |
| publishedAtMin | No | Earliest publish date (inclusive), as YYYY-MM-DD in UTC, e.g. 2026-06-01. | |
| repostCountMax | No | Maximum on-platform repost count. | |
| repostCountMin | No | Minimum on-platform repost count. | |
| collectCountMax | No | Maximum save/collect count. | |
| collectCountMin | No | Minimum save/collect count. | |
| commentCountMax | No | Maximum comment count. | |
| commentCountMin | No | Minimum comment count. | |
| interactionRateMax | No | Maximum interaction rate, as a decimal. Interaction rate = (likes + comments + shares + saves) / plays. | |
| interactionRateMin | No | Minimum interaction rate, as a decimal. Interaction rate = (likes + comments + shares + saves) / plays. | |
| creatorFollowerCountMax | No | Maximum follower count of the video's creator. | |
| creatorFollowerCountMin | No | Minimum follower count of the video's creator. |