---
title: "Start audience match analysis"
method: POST
path: "/v1/creators/audience-match"
tags: ["Analysis"]
---

# Start audience match analysis

`POST /v1/creators/audience-match`

## Request

- Base URL: `https://api.toksta.com`
- URL: `https://api.toksta.com/v1/creators/audience-match`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/toksta/apis/toksta-public-api/docs/v1/creators/audience-match/post.ts> (a function with typed inputs; its response is checked against the schema)

Start LinkedIn audience-fit analysis for a creator selection. Requires a user-scoped key.

**Selection (provide exactly one):** `creator_ids`, `result_set_id`, or `result_set_ids`.

**Audience criteria:** for ad hoc runs (no `campaign_id`) provide at least one of `campaign_brief`, `target_audience`, `audience_keywords` (array), or `target_audience_criteria` (array). When `campaign_id` is set, criteria are read from the campaign.

Returns `202` with **prefixed** job IDs in the form `audience-fit:<uuid>`. Use those IDs with `POST /v1/audience-match/results` or `/details`. Cost: 10/20/30 credits per analysis based on `analysis_depth`.

## Request body

- object
  - `creator_ids` string[]: Creator UUIDs to operate on. Takes precedence over result_set_id / result_set_ids when provided.
  - `result_set_id` string: A single `result_set_id` returned by a prior discovery search. Resolved to its ranked creators.
  - `result_set_ids` string[]: Multiple result set IDs to merge (dedupe) into one creator selection.
  - `top_n` integer: When selecting from result set(s), take only the top N ranked creators.
  - `ranks` integer[]: When a single result_set_id is provided, select specific 1-based ranks (e.g. [1,3,5]).
  - `campaign_id` string: Optional campaign UUID. When set, audience criteria come from the campaign.
  - `campaign_brief` string: Free-text brief describing the target audience (ad hoc).
  - `target_audience` string: Alias for campaign_brief (ad hoc).
  - `audience_keywords` string[]: Audience keywords (ad hoc). Alias: `keywords`.
  - `target_audience_criteria` string[]: Free-form audience criteria strings (e.g. job titles, seniorities, industries) for ad hoc runs.
  - `analysis_depth` 'quick_scan' | 'deep_dive' | 'comprehensive': Analysis depth. quick_scan (10cr), deep_dive (20cr), comprehensive (30cr). Defaults to quick_scan.

## Response `202`

Audience match jobs queued. Job IDs are prefixed `audience-fit:<uuid>`.

- object: Audience match jobs queued. Job IDs are prefixed `audience-fit:<uuid>`.
  - `success` true, required
  - `data` object, required: Operation payload. See the example for the exact field structure.
  - `meta` object, required
    - `request_id` string, required
    - `trace_id` string

## Other responses

- `400`: Bad request or validation error (`BAD_REQUEST` / `VALIDATION_ERROR`).
- `401`: Missing, invalid, or revoked API key.
- `402`: Insufficient credits for this operation.
- `403`: API access disabled or workspace entitlement required.
- `404`: Resource not found, or result expired past retention.
- `429`: Rate limit exceeded — back off per `Retry-After`.
- `500`: Unexpected server error.
- `501`: Endpoint is registered but not implemented yet.

---

[API](https://skmtc.dev/toksta/apis/toksta-public-api.md) - [All operations](https://skmtc.dev/toksta/apis/toksta-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/toksta/apis/toksta-public-api/revisions/a8cf8189fdd1?raw)