---
title: "Search creators by what they say (transcript mode)"
method: POST
path: "/ai-search/transcript"
tags: ["AI Search"]
---

# Search creators by what they say (transcript mode)

`POST /ai-search/transcript`

Find creators whose video transcripts match a natural-language phrase. `match_sources` selects spoken audio and/or on-screen text (defaults to audio). Matched videos carry `match_type` and a `snippet`. Requires a single `x-shop-id`; availability is gated per region.

## Request body

- AISearchTranscriptRequest — POST /ai-search/transcript request body — spoken-word (transcript) search.
  - `query` string, required — Natural-language phrase to match against creator video transcripts (required).
  - `match_sources` string[] — Which transcript sources to search: 'audio' (spoken words) and/or 'video' (on-screen text). Defaults to ['audio']. Duplicates are de-duplicated.
  - `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.
  - `page` integer
  - `page_size` integer

## 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/5eefff009b5b/schema)