Audience runs

Overview

Audience results are read from runs. A run can be manual, daily, or preview; public run creation supports manual runs. Daily runs are queued by the worker scheduler for active audiences.

Queue a manual run

POST /v1/intent/audiences/{id}/runs
x-api-key: YOUR_API_KEY
Idempotency-Key: unique-client-retry-key
Content-Type: application/json

{
  "runType": "manual"
}

Use Idempotency-Key when retrying from a client. The key can be up to 120 characters.

Response

{
  "data": {
    "id": "ad53af16-efbc-4fe1-a764-ded7181653a1",
    "audienceId": "8c049a20-3385-42da-b710-0d038eff5812",
    "organizationId": "a1657c63-bed2-41b4-b816-f09614490057",
    "status": "queued",
    "runType": "manual",
    "configHash": "8e7f74e01dd2ce8cd0c12969155eac44d624818f1de711f175aab34d2ab193a8",
    "dataDate": "2026-05-04",
    "candidateCount": 0,
    "resultCount": 0,
    "attempts": 0,
    "createdAt": "2026-05-05T09:30:00.000Z"
  }
}

List runs

GET /v1/intent/audiences/{id}/runs?limit=25
x-api-key: YOUR_API_KEY

{
  "data": [
    {
      "id": "ad53af16-efbc-4fe1-a764-ded7181653a1",
      "audienceId": "8c049a20-3385-42da-b710-0d038eff5812",
      "status": "completed",
      "runType": "daily",
      "dataDate": "2026-05-04",
      "candidateCount": 121463,
      "resultCount": 20,
      "startedAt": "2026-05-05T07:49:00.675Z",
      "completedAt": "2026-05-05T07:49:03.000Z"
    }
  ]
}

Cancel a queued run

DELETE /v1/intent/audiences/{id}/runs/{runId}
x-api-key: YOUR_API_KEY

Only queued runs can be cancelled. Completed, failed, running, or already cancelled runs cannot be cancelled.

Run status values

Status	Meaning
`queued`	Waiting for a worker
`running`	Materialization is in progress
`completed`	Results, stats, and exports are available
`failed`	Processing failed; inspect `errorCode` and `errorMessage`
`cancelled`	The queued run was cancelled

Notes

Each run is a separate snapshot.
Use the run ID for results, stats, and exports.
Result endpoints return 202 while a run is queued or running.
Daily refresh is worker-owned; do not trigger daily runs from UI clients.

Next steps

Read Get people to retrieve hydrated results from a completed run.
Read Stats and export to inspect fill rates or download CSV data.

Start here

Workflow guides

Topic discovery

Audience builder

Audience results

Overview

Queue a manual run

Response

List runs

Cancel a queued run

Run status values

Notes

Next steps

​Overview

​Queue a manual run

​Response

​List runs

​Cancel a queued run

​Run status values

​Notes

​Next steps

Overview

Queue a manual run

Response

List runs

Cancel a queued run

Run status values

Notes

Next steps