# Discovery

URL: https://docs.sigment.ai/tools/discovery

Find new creators for a topic, or look up creators you already know.

Use `search_creators` for known handles or names (free), and `discover_creators` for new creators on a topic (20 credits). A discovery returns a `job_id`: wait for it with [`wait_for_job`](https://docs.sigment.ai/tools/jobs), then read it with `get_discovery`.

### search_creators

Look up creators by handle or name across Instagram and YouTube (free, 60 per hour). For finding NEW creators by topic use discover_creators.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `query` | `string` | yes |  | 2–200 chars |
| `limit` | `integer` | no | 5 | 1–10 |

### get_creator

Creator profile with audience demographics (age, gender, geo) where the creator connected their account. creator_id: Instagram handle or sigment_creator_id; YouTube/TikTok: the `id` from search.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `platform` | `"instagram" \| "youtube" \| "tiktok"` | yes |  |  |
| `creator_id` | `string` | yes |  | 1–100 chars |

### discover_creators

Find new creators for a topic (e.g. 'vegan fitness moms'). Costs 20 credits (free if the same topic ran in the last 24h). Returns a job_id: wait_for_job, then get_discovery.

Kind: asks before running

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `topic` | `string` | yes |  | 2–200 chars |
| `max_credits` | `integer` | yes |  | 0–1000 |
| `platforms` | `("instagram" \| "youtube" \| "tiktok")[]` | no | ["instagram"] | 1–3 items |
| `min_followers` | `integer` | no | 2000 | ≥ 0 |
| `per_subtopic_limit` | `integer` | no | 10 | 1–20 |
| `workspace_id` | `string` | no |  | 1–100 chars |

### list_discoveries

Past discovery searches (newest first) — resume earlier work from here.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `limit` | `integer` | no | 10 | 1–50 |

### get_discovery

Creators found by a discovery, grouped by subtopic, plus the strongest audience overlaps. Pass `handles` to get the overlaps involving those creators instead of the global top 15. For the full interest graph of a creator set, analyze_creators it and read get_analysis_result.interest_graph.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `discovery_id` | `string` | yes |  | 1–100 chars |
| `max_per_group` | `integer` | no | 10 | 1–20 |
| `handles` | `string[]` | no |  | ≤ 50 items |