REreacherapp
AI Search

Search creators with natural language (profile mode)

Changed on

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. Agency keys may run this brand-agnostically across all their brands at once by sending x-shop-id: all with an owned anchor_shop query param, whose region is the search market; in that mode the per-shop shop_gmv field is omitted.

post/ai-search/creators

Request

  • Base URL
    https://api.reacherapp.com/public/v1
  • URL
    https://api.reacherapp.com/public/v1/ai-search/creators
  • Auth
    API key in header x-api-key and API key in header x-shop-id

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.

has_ad_videosboolean nullable

Only creators whose search card shows (true) / doesn't show (false) a video that ran as a paid TikTok ad.

has_ai_videosboolean nullable

Only creators whose search card shows (true) / doesn't show (false) a video TikTok labels AI-generated.

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=$1.5M+). 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

  • 2840b044a7daRevision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

  • 291230805105Revision changes
    • info

      api operation id search_creators_ai_search_creators_post removed and replaced with ai_search_creators

    • info

      added the optional property / to the response with the status

    • info

      response property pagination/total deprecated

    • info

      added the required property / to the response with the status