Audience runs

Overview

Audience results are read from runs. A run can be manual, daily, or preview; public run creation supports manual runs. Daily refreshes are scheduled for eligible 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. Reuse it for retries of the same intended run; choose a new key for a new run. An existing in-flight run may also be returned instead of creating a duplicate. The audience must be active before you queue a run. A successful queue response is 202, not confirmation that contacts are ready.

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.
Request only manual runs through the public run-creation API; daily refreshes are scheduled automatically.
Pausing stops future automatic refreshes. Read dailyRefreshEnabled and account access instead of assuming every active audience has the same refresh entitlement.

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 and filters

Topic lists

Audience builder

Visitor overlap and analytics

Audience results

Integrations

Destinations

Deliveries

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