TOtoksta
Analysis

Start audience match analysis

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.

post/v1/creators/audience-match

Request

Request body

creator_idsstring[]

Creator UUIDs to operate on. Takes precedence over result_set_id / result_set_ids when provided.

result_set_idstring

A single result_set_id returned by a prior discovery search. Resolved to its ranked creators.

result_set_idsstring[]

Multiple result set IDs to merge (dedupe) into one creator selection.

top_ninteger

When selecting from result set(s), take only the top N ranked creators.

ranksinteger[]

When a single result_set_id is provided, select specific 1-based ranks (e.g. [1,3,5]).

campaign_idstring

Optional campaign UUID. When set, audience criteria come from the campaign.

campaign_briefstring

Free-text brief describing the target audience (ad hoc).

target_audiencestring

Alias for campaign_brief (ad hoc).

audience_keywordsstring[]

Audience keywords (ad hoc). Alias: keywords.

target_audience_criteriastring[]

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.

Example request

{
  "creator_ids": [
    "f0e1d2c3-b4a5-4678-9abc-def012345678"
  ],
  "target_audience_criteria": [
    "VP Marketing",
    "Head of Growth",
    "B2B SaaS"
  ],
  "analysis_depth": "quick_scan"
}

Response

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

successtrue required
dataobject required

Operation payload. See the example for the exact field structure.

Example response

{
  "success": true,
  "data": {
    "creators_requested": 1,
    "selection": {
      "source": "creator_ids",
      "selected_count": 1
    },
    "campaign_id": null,
    "analysis_depth": "quick_scan",
    "jobs_created": 1,
    "job_ids": [
      "audience-fit:a5f1eeb5-ee98-41bc-8b2c-3d4e5f6a7b8c"
    ],
    "jobs": [
      {
        "creator_id": "f0e1d2c3-b4a5-4678-9abc-def012345678",
        "analysis_id": "a5f1eeb5-ee98-41bc-8b2c-3d4e5f6a7b8c",
        "job_id": "audience-fit:a5f1eeb5-ee98-41bc-8b2c-3d4e5f6a7b8c",
        "status": "pending",
        "cached": false,
        "message": "Audience analysis started. This may take a few minutes.",
        "creator_name": "Jane Marketer",
        "profile_url": "https://www.linkedin.com/in/jane-marketer/"
      }
    ],
    "failures": []
  },
  "meta": {
    "request_id": "req_01HXYZ...",
    "trace_id": "4f1d...c2"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.