---
title: "Find creators similar to seed creators (lookalike mode)"
method: POST
path: "/ai-search/lookalike"
tags: ["AI Search"]
---

# Find creators similar to seed creators (lookalike mode)

`POST /ai-search/lookalike`

## Request

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

Find creators similar to a seed set. Seed from any of: `seed_creator_ids` (handles or ids, up to 50), a `seed_crm_group_id`, a `seed_list_id`, or a text `query`. CRM group / list seeds are resolved to creators server-side, scoped to your shop. Seeds are excluded from the results. Requires a single `x-shop-id`; availability is gated per region.

## Request body

- AISearchLookalikeRequest: POST /ai-search/lookalike request body — creator->creator lookalike. Seed from any ONE (or more) of: explicit ``seed_creator_ids`` (handles or ids, <=50), a ``seed_crm_group_id``, a ``seed_list_id``, or a text ``query`` (text-description fallback). CRM group / saved list are resolved to creator handles SERVER-SIDE, ownership-scoped to the caller's shop, so a caller can only seed from cohorts their key owns. Seeds are excluded from the results downstream.
  - `seed_creator_ids` string[], nullable: Seed creators (TikTok handles or ids), up to 50. The result set is creators similar to these seeds.
  - `seed_crm_group_id` string, nullable: Seed from an existing CRM group's members (resolved server-side, scoped to your shop).
  - `seed_list_id` integer, nullable: Seed from a saved list's members (resolved server-side, scoped to your shop).
  - `query` string, nullable: Text-description lookalike: describe the kind of creator to find. Used when no seed cohort is supplied.
  - `filters` object, nullable: Optional creator filters, 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: Standard pagination fields; `total` is the deprecated alias of `total_count`.
    - `total_count` integer, required
    - `page` integer, required
    - `page_size` integer, required
    - `total_pages` integer: Pages available at this page_size.
    - `total` integer, required: Deprecated alias of `total_count`; use `total_count`.
  - `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

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-09-19** `291230805105`: 4 info
  - api operation id `search_lookalike_ai_search_lookalike_post` removed and replaced with `ai_search_lookalike`
  - added the optional property `pagination/total_pages` to the response with the `200` status
  - response property `pagination/total` deprecated
  - added the required property `pagination/total_count` to the response with the `200` status

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/ai-search/lookalike/post.md)

---

[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.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)