---
title: "Search creators with natural language (profile mode)"
method: POST
path: "/ai-search/creators"
tags: ["AI Search"]
---

# Search creators with natural language (profile mode)

`POST /ai-search/creators`

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`.

## Request body

- AISearchCreatorsRequest — POST /ai-search/creators request body.
  - `min_gmv` number, nullable — Minimum GMV.
  - `max_gmv` number, nullable — Maximum GMV.
  - `min_units_sold` number, nullable — Minimum units sold.
  - `max_units_sold` number, nullable — Maximum units sold.
  - `min_post_rate` number, 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_rate` number, nullable — Maximum post rate (sample-fulfillment %) on a 0–100 scale, NOT 0–1.
  - `min_engagement_rate` number, nullable — Minimum engagement rate, 0–100.
  - `max_engagement_rate` number, nullable — Maximum engagement rate, 0–100.
  - `min_average_views` number, nullable — Minimum average views.
  - `max_average_views` number, nullable — Maximum average views.
  - `min_followers` integer, nullable — Minimum follower count.
  - `max_followers` integer, nullable — Maximum follower count.
  - `has_email` boolean, nullable — Only creators with (true) / without (false) an email.
  - `categories` string[], nullable — Product categories (canonical names).
  - `gender` string[], nullable — Creator gender, e.g. ["female"].
  - `creator_ethnicity` string[], nullable — Creator ethnicity.
  - `age_range` string[], nullable — Creator age range, e.g. ["25-34"].
  - `community` string[], nullable — Community hashtags (US/UK/DE/ES only). Fetch valid values from GET /ai-search/hashtags.
  - `creator_level` string[], nullable — Creator GMV level tier, e.g. ["L5","L6","L7"] (L0=$0 through L7=>$1M). Same tiers the filter vocabulary lists as "Creator Level".
  - `languages` string[], nullable — Creator languages, e.g. ["english"].
  - `audience_age` string[], nullable — Audience (follower) age band.
  - `audience_gender` string[], nullable — Audience (follower) gender.
  - `content_style` string[], nullable — Content style, e.g. ["lifestyle"].
  - `production_quality` string[], nullable — Production quality, e.g. ["raw_ugc"].
  - `personality_tone` string[], nullable — Personality / tone, e.g. ["relatable"].
  - `face_visibility` string[], nullable — Face visibility, e.g. ["sometimes"].
  - `body_type` string[], nullable — Body type (~⅓ of creators populated).
  - `hair_type` string[], nullable — Hair type, e.g. ["wavy"].
  - `query` string, nullable — Natural-language search query. Whitespace-only is treated as no query (browse mode).
  - `filters` object, 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.
  - `page` integer
  - `page_size` integer
  - `disable_handle_pin` boolean — 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 `200`

Successful Response

- AISearchCreatorsResponse
  - `data` AISearchCreator[], required
    - `creator_name` string, nullable — Creator's TikTok handle. Stable identifier for cross-referencing.
    - `categories` string[], nullable
    - `follower_count` integer, nullable
    - `gmv` number, nullable — Creator's OVERALL (global, cross-shop) GMV from their public TikTok profile. Sparse: TikTok exposes it for only ~10% of creators, so it is often null even for active sellers. For the GMV a creator drove for YOUR shop, use `shop_gmv`.
    - `shop_gmv` number, nullable — Lifetime GMV this creator drove for the REQUESTING shop (crm_creator_summary.gmv). Populated for creators in your shop's affiliate roster; null for creators your shop has no CRM record of. Distinct from the sparse global `gmv`.
    - `post_rate` number, nullable
    - `engagement_rate` number, nullable
    - `average_views` number, nullable — Average views per video. Null when not available for this result.
    - `units_sold` integer, nullable — Estimated units sold. Null when not available for this result.
    - `bio` string, nullable — Creator bio.
    - `top_videos` AISearchVideo[]
      - `video_id` string, required
      - `tiktok_url` string, nullable
      - `views` integer, nullable
      - `match_type` string, nullable — Why this video matched, for the transcript/video modes: 'audio' (spoken words), 'video' (on-screen visual/text). Null on the profile/lookalike modes, where top_videos are the creator's representative videos rather than per-query matches.
      - `snippet` string, nullable — Matched transcript excerpt (transcript mode only). Null otherwise.
    - `match_count` integer, nullable — Number of this creator's videos that matched the query (transcript/video modes). Null on profile/lookalike.
    - `match_score` number, nullable — Relevance score of this creator's best match (transcript/video modes) or similarity to the lookalike seeds (lookalike mode). Null on profile.
  - `pagination` AISearchPagination, required
    - `total` integer, required
    - `page` integer, required
    - `page_size` integer, required
  - `exact_handle_match` boolean — 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_handle` string, nullable — The normalized handle that matched (e.g. 'kriseatsnyc'), or null when there was no exact-handle pin.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) · [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/3ea20a9f734b/schema)