openapi_v2_tiktok_creators_search
Tiktok Creators Search
Search TikTok creators by profile, category, content, and commerce signals.
Data is from the latest daily creator snapshot within the fallback window (region = US in v1). Related-product sales fields describe the overall product sales for SPUs the creator promoted, not creator-attributed GMV. carryVideoSales30d / carryVideoRevenue30d are creator-attributed lower bounds (only carry videos with at least 500 plays are counted) and are available as sortBy values; results sort by relatedProductSaleAmt30d descending unless sortBy is set.
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[TikTokCreator]]",
"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. | |
| sortBy | No | Sort field for creator search, e.g. carryVideoRevenue30d / carryVideoSales30d for creator-attributed carry performance. Default relatedProductSaleAmt30d. | relatedProductSaleAmt30d |
| keyword | No | Case-insensitive substring match against creator handle or nickname. | |
| pageSize | No | Page size, 1–100. Default 20. | |
| sortOrder | No | Sort direction. Default desc. | desc |
| followerCountMax | No | Maximum follower count from the latest creator profile snapshot. | |
| followerCountMin | No | Minimum follower count from the latest creator profile snapshot. | |
| saleCategoryPath | No | Promoted product category path to filter creators by trailing-30-day carry categories. Supports 1 to 3 levels, e.g. ['Beauty & Personal Care', 'Skin Care', 'Face Serums']. | |
| carryVideo30dCountMax | No | Maximum number of newly published carry videos over the trailing 30 days. | |
| carryVideo30dCountMin | No | Minimum number of newly published carry videos over the trailing 30 days. | |
| carryVideoSales30dMax | No | Maximum units sold over the trailing 30 days attributed to this creator's carry videos. Creator-attributed lower bound; counts only carry videos with at least 500 plays. | |
| carryVideoSales30dMin | No | Minimum units sold over the trailing 30 days attributed to this creator's carry videos. Creator-attributed lower bound; counts only carry videos with at least 500 plays. | |
| carryVideoRevenue30dMax | No | Maximum GMV over the trailing 30 days attributed to this creator's carry videos, in USD. Creator-attributed lower bound; counts only carry videos with at least 500 plays. | |
| carryVideoRevenue30dMin | No | Minimum GMV over the trailing 30 days attributed to this creator's carry videos, in USD. Creator-attributed lower bound; counts only carry videos with at least 500 plays. | |
| carryVideoTotalCountMax | No | Maximum total known carry-video count. | |
| carryVideoTotalCountMin | No | Minimum total known carry-video count. | |
| follower30dDeltaCountMax | No | Maximum follower-count change over the trailing 30 days. | |
| follower30dDeltaCountMin | No | Minimum follower-count change over the trailing 30 days. | |
| follower30dGrowthRateMax | No | Maximum follower growth rate over the trailing 30 days, as a decimal. | |
| follower30dGrowthRateMin | No | Minimum follower growth rate over the trailing 30 days, as a decimal. | |
| promotedProduct30dCountMax | No | Maximum number of products linked to newly published carry videos over the trailing 30 days. | |
| promotedProduct30dCountMin | No | Minimum number of products linked to newly published carry videos over the trailing 30 days. | |
| relatedProductSaleAmt30dMax | No | Maximum overall GMV over the trailing 30 days for products related to this creator, in USD. This is not creator-attributed GMV. | |
| relatedProductSaleAmt30dMin | No | Minimum overall GMV over the trailing 30 days for products related to this creator, in USD. This is not creator-attributed GMV. | |
| relatedProductSaleCnt30dMax | No | Maximum overall units sold over the trailing 30 days by products related to this creator. Each SPU is counted once; this is not creator-attributed sales. | |
| relatedProductSaleCnt30dMin | No | Minimum overall units sold over the trailing 30 days by products related to this creator. Each SPU is counted once; this is not creator-attributed sales. | |
| promotedProductTotalCountMax | No | Maximum total known promoted product count. | |
| promotedProductTotalCountMin | No | Minimum total known promoted product count. | |
| carryVideoInteraction30dRateMax | No | Maximum carry-video interaction rate over the trailing 30 days. | |
| carryVideoInteraction30dRateMin | No | Minimum carry-video interaction rate over the trailing 30 days. | |
| carryVideoPlay30dIncrementCountMax | No | Maximum play-count increment across carry videos over the trailing 30 days. | |
| carryVideoPlay30dIncrementCountMin | No | Minimum play-count increment across carry videos over the trailing 30 days. |