Skip to main content

​
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

StatusMeaning
queuedWaiting for a worker
runningMaterialization is in progress
completedResults, stats, and exports are available
failedProcessing failed; inspect errorCode and errorMessage
cancelledThe 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.