Sign in
AI Search

Search creators with natural language (profile mode)

Search the global TikTok creator universe with a natural-language query. Returns paginated creator results scored against the query, with optional browse mode when query is omitted (returns top creators in the shop's region). Requires a single x-shop-id — the shop's region determines which regional creator table is searched. Launched regions use the v3 profile pipeline; other regions fall back to the v2 pipeline (profile is never region-gated). Units: the gmv field is in US dollars; post_rate/engagement_rate are on a 0–100 scale (NOT 0–1). Filter on an exact GMV/post-rate via the flat params (min_gmv, min_post_rate, …) or the equivalent nested filters.

post/ai-search/creators

Request body

min_gmvnumber nullable

Minimum GMV.

max_gmvnumber nullable

Maximum GMV.

min_units_soldnumber nullable

Minimum units sold.

max_units_soldnumber nullable

Maximum units sold.

min_post_ratenumber nullable

Minimum post rate (sample-fulfillment %) on a 0–100 scale, NOT 0–1. Same metric the automations endpoint calls fulfillment_rate. US/UK only.

max_post_ratenumber nullable

Maximum post rate (sample-fulfillment %) on a 0–100 scale, NOT 0–1.

min_engagement_ratenumber nullable

Minimum engagement rate, 0–100.

max_engagement_ratenumber nullable

Maximum engagement rate, 0–100.

min_average_viewsnumber nullable

Minimum average views.

max_average_viewsnumber nullable

Maximum average views.

min_followersinteger nullable

Minimum follower count.

max_followersinteger nullable

Maximum follower count.

has_emailboolean nullable

Only creators with (true) / without (false) an email.

categoriesstring[] nullable

Product categories (canonical names).

genderstring[] nullable

Creator gender, e.g. ["female"].

creator_ethnicitystring[] nullable

Creator ethnicity.

age_rangestring[] nullable

Creator age range, e.g. ["25-34"].

communitystring[] nullable

Community hashtags (US/UK/DE/ES only). Fetch valid values from GET /ai-search/hashtags.

creator_levelstring[] nullable

Creator GMV level tier, e.g. ["L5","L6","L7"] (L0=$0 through L7=>$1M). Same tiers the filter vocabulary lists as "Creator Level".

languagesstring[] nullable

Creator languages, e.g. ["english"].

audience_agestring[] nullable

Audience (follower) age band.

audience_genderstring[] nullable

Audience (follower) gender.

content_stylestring[] nullable

Content style, e.g. ["lifestyle"].

production_qualitystring[] nullable

Production quality, e.g. ["raw_ugc"].

personality_tonestring[] nullable

Personality / tone, e.g. ["relatable"].

face_visibilitystring[] nullable

Face visibility, e.g. ["sometimes"].

body_typestring[] nullable

Body type (~⅓ of creators populated).

hair_typestring[] nullable

Hair type, e.g. ["wavy"].

querystring nullable

Natural-language search query. Whitespace-only is treated as no query (browse mode).

filtersobject nullable

Optional creator filters (categories, follower/GMV ranges, etc.), same shape as the portal search filters. post_rate is on a 0–100 scale (sample-fulfillment %). Unrecognized filter keys are rejected with a 400 rather than silently ignored. Cannot be combined with the flat filter params (min_gmv, gender, hair_type, etc.) inherited above.

pageinteger
page_sizeinteger
disable_handle_pinboolean

When true, skip the deterministic exact-@handle pin and return pure semantic results (powers a 'show all matches / full search' flow). When a query is an exact creator handle, the default (false) pins that creator first and sets exact_handle_match/exact_handle on the response.

Response

Successful Response

exact_handle_matchboolean

True iff the query was an exact creator handle (or a short brand name that resolves to one) and that creator was pinned as the first result. Lets a client show an 'exact creator found' affordance and offer a full semantic search via disable_handle_pin=true.

exact_handlestring nullable

The normalized handle that matched (e.g. 'kriseatsnyc'), or null when there was no exact-handle pin.

Changes

No recorded changes to this endpoint across all 2 revisions of this API.