> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creatordb.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Creators
> Search for TikTok creators using advanced filters such as `displayName`, follower count, content performance, and more. Supports fuzzy search, pagination, and multiple filter combinations with up to 10 filters per request. The `creatorList` is, by default, sorted by `displayName`. Custom sorting can be applied using the `sortBy` parameter.
Optionally pass `fields` to enrich each search result with data from other endpoints. Enrichment is billed per result returned, using each endpoint's own pricing rules. Fractional calls must be enabled on your API key. For details, see [Fractional Calls](/api-v3/fractional-calls).
## OpenAPI
````yaml /api-v3/api-v3.yaml post /tiktok/search
openapi: 3.1.0
info:
version: 1.0.0
title: CreatorDB Headless API V3
description: '# CreatorDB Headless API V3'
contact:
name: CreatorDB
url: https://www.creatordb.app
email: support@creatordb.app
license:
url: http://www.apache.org/licenses/LICENSE-2.0.html
name: Apache 2.0
servers:
- url: https://apiv3.creatordb.app
description: Production Environment (CreatorDB Headless API V3)
security:
- ApiKeyAuth: []
tags:
- name: Brand
description: Brand analysis endpoints including sponsor search and brand reports.
- name: Facebook
description: Facebook creator data endpoints with metrics and search capabilities.
- name: General Operations
description: >-
General-purpose endpoints such as API status, content retrieval, and
cross-platform operations.
- name: Instagram
description: >-
Instagram creator data endpoints with metrics and advanced search
capabilities.
- name: Niches
description: >-
Niche-related endpoints for content category analysis and related
searches.
- name: Threads
description: Threads creator data endpoints with basic metrics and historical data.
- name: TikTok
description: >-
TikTok creator data endpoints with metrics and advanced search
functionality.
- name: Topic
description: Topic-based analysis and reporting endpoints for content categorization.
- name: YouTube
description: >-
YouTube creator data endpoints including basic metrics, historical data,
and detailed analytics.
paths:
/tiktok/search:
post:
tags:
- TikTok
summary: Search Creators
description: >-
Search for TikTok creators using advanced filters such as `displayName`,
follower count, content performance, and more. Supports fuzzy search,
pagination, and multiple filter combinations with up to 10 filters per
request. The `creatorList` is, by default, sorted by `displayName`.
Custom sorting can be applied using the `sortBy` parameter.
Optionally pass `fields` to enrich each search result with data from
other endpoints. Enrichment is billed per result returned, using each
endpoint's own pricing rules. Fractional calls must be enabled on your
API key. For details, see [Fractional Calls](/api-v3/fractional-calls).
operationId: searchTiktok
requestBody:
content:
application/json:
schema:
type: object
description: TikTok search request parameters.
properties:
filters:
type: array
description: >-
Filter objects that include `filterName`, `op`, and `value`.
For all accepted `filterName` values and their data types,
see [Configuring Custom Search Filters and
Examples](https://docs.creatordb.app/api-v3/configuring_advanced_search_filters#available-filtername-&-sortby).
maxItems: 10
items:
type: object
properties:
filterName:
type: string
description: The field to apply the filter on.
op:
type: string
enum:
- in
- '>'
- '='
- <
description: >-
The comparison operator. Accepted values include `in`,
`>`, `=`, `<`.
-String fields accept: `=`,
`in`.
-Number fields accept: `>`, `=`, `<`.
-Boolean fields accept: `=`
value:
description: >-
Type depends on the `filterName`.
- String
fields accept `string` or `string[]`.
- Number
fields accept `number`.
-Boolean fields accept
`boolean`.
- Operator `in` accepts `string[]`,
operator `=` accepts string for string fields.
anyOf:
- type: number
- type: array
maxItems: 100
items:
type: string
- type: boolean
isFuzzySearch:
type: boolean
description: >-
When `true`, performs a fuzzy match for `string` type
`filterName`.
required:
- filterName
- op
- value
desc:
type: boolean
description: >-
Sort order for results. `true` for descending, `false` for
ascending order.
sortBy:
type: string
description: >-
Field to sort creators by. For example, `totalFollowers`
sorts by follower count.
pageSize:
type: integer
description: 'Number of results per page. Maximum: 100.'
minimum: 1
maximum: 100
offset:
type: integer
description: Number of records to skip before returning results.
minimum: 0
fields:
type: object
description: >-
Enrich each search result with data from other endpoints on
the same platform (e.g. `profile`, `contact`). Enrichment is
billed per result returned, using each endpoint's pricing
rules. Each key is a bare endpoint name, and each key's
value follows that endpoint's fractional shape. Per-field
costs are not published yet.
properties:
profile:
type: array
items:
type: string
description: Profile fields to add to each search result.
performance:
type: array
items:
type: string
description: Performance blocks to add to each search result.
audience:
type: array
items:
type: string
description: Audience fields to add to each search result.
contact:
type: array
items:
type: string
description: Contact fields to add to each search result.
content-detail:
type: object
description: >-
Per-item counts, e.g. { "recentVideos": 5 }. `0`,
`null`, or omission returns zero items for that field.
Valid field names vary by platform. For details, see
[Fractional Calls](/api-v3/fractional-calls).
performance-history:
type: object
required:
- pastDayRange
properties:
pastDayRange:
type: string
pattern: ^[1-9]\d*$
description: >-
Date range bucket, e.g. { "pastDayRange": 90 }. For
pricing, see [Performance history
pricing](/api-v3/api-credit-usage#performance-history-pricing).
additionalProperties: false
examples:
- profile:
- country
content-detail:
recentVideos: 3
performance-history:
pastDayRange: 90
required:
- filters
- pageSize
- offset
examples:
- filters:
- filterName: displayName
op: '='
value: beast
isFuzzySearch: true
desc: true
sortBy: displayName
pageSize: 10
offset: 0
responses:
'200':
description: TikTok search results returned successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: >-
Search results containing TikTok creators and pagination
information.
properties:
creatorList:
type: array
description: Creator objects matching the search query.
items:
type: object
description: Creator details in search results.
properties:
displayName:
type: string
description: The TikTok account name.
examples:
- TikTok
uniqueId:
type: string
description: The TikTok handle.
examples:
- tiktok
avatarUrl:
type: string
description: The profile picture URL.
examples:
- >-
https://p16-sign-va.tiktokcdn.com/tos-maliva-avt...
totalFollowers:
type: integer
description: Total number of followers.
minimum: 0
examples:
- 38100
required:
- displayName
- uniqueId
- avatarUrl
- totalFollowers
hasNextPage:
type: boolean
description: '`true` if there is a next page of results.'
examples:
- true
nextOffset:
type: integer
description: >-
The offset value to use for retrieving results on the
next page.
minimum: 0
examples:
- 100
required:
- creatorList
- hasNextPage
- nextOffset
creditsUsed:
type: integer
description: Number of API credits consumed by this request.
examples:
- 1
creditsAvailable:
type: integer
description: Number of API credits remaining.
examples:
- -1
traceId:
type: string
description: Unique trace ID for each request.
examples:
- f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0
timestamp:
type: integer
description: >-
Time the response was generated, represented as a Unix
timestamp in milliseconds.
examples:
- 1750732453635
errorCode:
type: string
description: >-
Error code returned if the request fails. Empty if the
request is successful.
examples:
- ''
errorDescription:
type: string
description: >-
Description of the error. Empty if the request is
successful.
examples:
- ''
success:
type: boolean
description: '`true` if the request is successful.'
examples:
- true
required:
- data
- traceId
- timestamp
- errorCode
- errorDescription
- success
- creditsUsed
- creditsAvailable
examples:
default:
value:
data:
creatorList:
- displayName: Ty Myers
uniqueId: tymyers
avatarUrl: >-
https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/95a314aa4befbecaa494aab7e5f6d0cb~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=e4f46e62&x-expires=1768428000&x-signature=Ms7U88fImoMAYs24EQrMEFjXFeY%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=sg1
totalFollowers: 779800
- displayName: barbie
uniqueId: barbiechicc
avatarUrl: >-
https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/30332117a44f5d110f8275983e3fb0fc~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=bb9952be&x-expires=1753714800&x-signature=zotHqzcGBpvhUi4mN1shxuXzMMU%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=my2
totalFollowers: 235500
- displayName: Rory Bland
uniqueId: rorybland
avatarUrl: >-
https://p16-sign-sg.tiktokcdn.com/tos-alisg-avt-0068/0de0d03ca26837b005fa4232e99d1e0e~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=352087cd&x-expires=1766962800&x-signature=xJmcAIYn2LqU1%2BDGvsbsMuRdHcE%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=maliva
totalFollowers: 238700
- displayName: π½ππππ₯πππ
uniqueId: fightzoneofficial0
avatarUrl: >-
https://p16-sign-sg.tiktokcdn.com/tos-alisg-avt-0068/0af25589aced72808751ba4c919db3c6~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=8d117d67&x-expires=1768467600&x-signature=KT2F8H%2FjReky%2BnpWpIvzSVW1OSs%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=maliva
totalFollowers: 22000
- displayName: Vanessa Mai
uniqueId: vanessa.mai
avatarUrl: >-
https://p19-common-sign-useastred.tiktokcdn-eu.com/tos-useast2a-avt-0068-euttp/712c5cb8b82a369c92cd5348ebacabc8~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=1b65e83f&x-expires=1768417200&x-signature=eXQtvZydJDiuHfYvZToJodLJjus%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=maliva
totalFollowers: 1700000
- displayName: linatejeirofc
uniqueId: linatejeirofc_
avatarUrl: >-
https://p16-sign-sg.tiktokcdn.com/tos-alisg-avt-0068/8ed9039524261f7d7cc699412c46d81a~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=7311701b&x-expires=1758495600&x-signature=ygXyejZSadm8bCM5wBCjBZNB0MA%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=my
totalFollowers: 4791
- displayName: TecnologΓas BG
uniqueId: tecnologiasbg
avatarUrl: >-
https://p16-sign-sg.tiktokcdn.com/tos-alisg-avt-0068/4a40b9a4d114d6e6856f61ead0d9ca83~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=9bf28d33&x-expires=1768230000&x-signature=Q%2FymfDk5JcT7EEjlNifmt5PBxfE%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=maliva
totalFollowers: 3296
- displayName: BHP
uniqueId: bhp
avatarUrl: >-
https://p16-sign-sg.tiktokcdn.com/tos-alisg-avt-0068/7340142468840554517~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=a8a6e235&x-expires=1768370400&x-signature=v8x9UBvD%2Bih2NC%2BfuCfvw8D%2BqZc%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=my
totalFollowers: 134500
hasNextPage: false
nextOffset: 0
creditsUsed: 1
creditsAvailable: -1
traceId: f790925aeaa82fa64b24c1400cbf5e3e
timestamp: 1768326490384
errorCode: ''
errorDescription: ''
success: true
'400':
description: Validation error.
content:
application/json:
schema:
type: object
title: ValidationErrorResponse
properties:
success:
const: false
error:
type: string
message:
type: string
timestamp:
type: integer
required:
- success
- error
- message
- timestamp
examples:
missing filters:
summary: Missing filters field
value:
success: false
error: VALIDATION_ERROR
message: At least 1 filter object is required.
timestamp: 1770099403116
invalid filterName:
summary: Invalid filterName
value:
success: false
error: VALIDATION_ERROR
message: >-
Invalid 'filterName' for TikTok. For accepted values, see:
https://docs.creatordb.app/api-v3/configuring_advanced_search_filters#configuring-filters-for-tiktok-advanced-search.
timestamp: 1770099403116
invalid pageSize:
summary: pageSize exceeds upper limit
value:
success: false
error: VALIDATION_ERROR
message: Exceeded max pageSize of 100. Must be between 1 and 100.
timestamp: 1770099403116
'429':
description: Exceeded quota or rate limit.
content:
application/json:
schema:
type: object
title: QuotaErrorResponse
description: Quota error response format.
properties:
success:
const: false
error:
type: string
message:
type: string
remainingPlanCredit:
type: number
required:
- success
- error
- message
- remainingPlanCredit
examples:
rate limit:
summary: Rate limit exceeded
value:
success: false
error: RATE_LIMIT_EXCEEDED
message: Too many requests. Please try again later.
quota exceeded:
summary: Credit quota exceeded
value:
success: false
error: QUOTA_EXCEEDED
message: Not enough credits to complete this request.
security:
- ApiKeyAuth: []
servers:
- url: https://apiv3.creatordb.app
description: Production Environment (CreatorDB Headless API V3)
x-codeSamples:
- lang: bash
label: cURL
source: |
curl -X POST "https://apiv3.creatordb.app/tiktok/search" \
-H "Content-Type: application/json" \
-H "api-key: " \
-d '{
"filters": [
{"filterName": "avgVideosEngagementRate", "op": ">", "value": 0.03},
{"filterName": "totalContents", "op": ">", "value": 20},
{"filterName": "followerGrowthIn30d", "op": ">", "value": 1000},
{"filterName": "avgVideosLikes", "op": ">", "value": 500}
],
"sortBy": "avgVideosEngagementRate",
"desc": true,
"pageSize": 50,
"offset": 0
}'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
description: The valid CreatorDB API key for authentication.
name: api-key
in: header
````