---
title: "Preview an AI Creator Search"
method: POST
path: "/workflows/search-preview"
tags: ["Workflows"]
---

# Preview an AI Creator Search

`POST /workflows/search-preview`

## Request

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

Who an `ai_creator_search` step would bring in first for this `query` and `mode`: creators new to the shop's CRM, past the settings' exclusions, best match first. Nothing is written and nobody is enrolled. Check a description here before putting it in a step — a query the search refuses answers 400 now rather than failing every scheduled run. An empty `creators` list means nobody matched for this shop. The search itself can take up to two minutes, and 502 SEARCH_UNAVAILABLE means it could not run — not that nobody matched. 429 means too many searches are already in flight; retry rather than rewording.

## Request body

- WorkflowSearchPreviewBody
  - `query` string, required: What the creators you want look like, in plain words — the same description an `ai_creator_search` step carries in its `query`.
  - `mode` 'profile' | 'transcript': `profile` matches a creator's bio and category; `transcript` matches what they say in their videos. Transcript search is switched off in some environments and answers 502 there.
  - `workflow_id` string, nullable: A saved workflow of this shop. Supply it to leave out the creators that workflow has already admitted, as one of its runs would.
  - `settings` object, nullable: Only `exclusions` changes the answer here; the rest is ignored.
  - `limit` integer: How many creators to name back.

## Response `200`

Successful Response

- EnvelopeWorkflowSearchPreviewPublic
  - `data` WorkflowSearchPreviewPublic, required
    - `creators` WorkflowPreviewCreatorPublic[]: Who one run of the search would admit first: new to this shop's CRM, past the workflow's exclusions, best match first. An empty list means nobody matched — a run would admit nobody and try again later.
      - `creator_id` string, required
      - `creator_name` string, nullable

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-10-20** `9353ed4982e8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/workflows/search-preview/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)