Runs
A run measures the audit’s prompts against the selected AI surfaces. Runs are asynchronous: start one, then poll. Beta: these shapes may change; see the changelog.
Poll a run’s status
Section titled “Poll a run’s status”GET /audits/{auditId}/run
The poll endpoint for an asynchronous run. runStatus is the run’s own state and auditStatus the audit’s; laneProgress is populated only while collecting. Respect retryAfterMs — it is the server’s guidance on when to poll next, and it varies with the phase the run is in. It is null once runStatus is COMPLETED or FAILED: stop polling. Polling faster does not make a run finish sooner, and this endpoint is rate-limited like any other.
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/run" \ -H "Authorization: Bearer $BEKET_API_KEY"Parameters
Section titled “Parameters”| Name | In | Required | Type | Description |
|---|---|---|---|---|
auditId | path | yes | string | The audit’s id. |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object | yes | |
data.auditId | string | yes | |
data.runStatus | string | yes | |
data.auditStatus | string | yes | |
data.laneProgress | object | null | Per-lane progress counters. Present only while collecting. | |
data.startedAt | string | null | ||
data.options | object | null | The options the run was started with. | |
data.error | string | null | ||
data.updatedAt | string | ||
data.retryAfterMs | integer | null | yes |
Example response (200)
Section titled “Example response (200)”{ "success": true, "data": { "auditId": "clrecorderaudit0000000001", "runStatus": "COMPLETED", "auditStatus": "COMPLETED", "laneProgress": null, "startedAt": null, "options": null, "error": null, "updatedAt": "2026-10-26T19:53:04.847Z", "retryAfterMs": null }}Start or resume a run directly
Section titled “Start or resume a run directly”POST /audits/{auditId}/run
The lower-level entry point to running an audit: it resumes and re-measures rather than re-asking the AI connectors for angles that already completed. Answers 202.
Prefer POST /audits/{auditId}/start for a normal integration — it takes the audit’s configuration and reports what the plan clamped. Reach for this one when you need to override run mechanics (crawl policy, snapshot behaviour, a specific angle subset).
This starts paid work. By default completed angles are not re-asked. Send refreshAnswers: true to re-ask the AI connectors for a COMPLETED audit — the full paid cost of a run; it is ignored for an audit in any other status, which resumes instead. forceRecover exists only to unstick a wedged run; a genuinely stale one recovers on its own without it.
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/run" \ -H "Authorization: Bearer $BEKET_API_KEY" \ -H "Content-Type: application/json" \ -d '{"domain":"<domain>"}'Parameters
Section titled “Parameters”| Name | In | Required | Type | Description |
|---|---|---|---|---|
auditId | path | yes | string | The audit’s id. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
domain | string | ||
angles | string[] | ||
queriesPerAngle | integer | ||
refreshAnswers | boolean | ||
forceRecover | boolean | ||
connectorTypes | string[] | ||
enrichCompetitors | boolean | ||
crawlPolicy | “skip” | “reuse_if_fresh” | “force_fresh” | ||
crawlFreshnessMaxAgeDays | integer | ||
createSnapshot | boolean | ||
snapshotLabel | string |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object | yes | |
data.auditId | string | yes | |
data.status | string | yes | |
data.startedAt | string | null | ||
data.options | object | The options the run was started with, after clamping. |
Start a configured audit
Section titled “Start a configured audit”POST /audits/{auditId}/start
The normal way to begin measuring: send the configuration (connectors, model, languages, locations, angles) and the run is enqueued. Answers 202 with an estimate of the run’s size plus the connector sets actually used — effectiveConnectors and droppedConnectors tell you what the plan clamped, which is why they are worth reading rather than assuming your selection was honoured verbatim.
This starts paid work. Poll GET /audits/{auditId}/run for progress; do not call this again to check on it. A 422 means the configuration was rejected — read the error message rather than retrying.
Requires status to be AWAITING_CONFIG or AWAITING_PROMPTS, and answers 409 otherwise — either because a run is already in flight, or because the audit was never prepared. A newly created audit is PENDING: call POST /audits/{auditId}/prepare first and wait for it to reach AWAITING_CONFIG.
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/start" \ -H "Authorization: Bearer $BEKET_API_KEY" \ -H "Content-Type: application/json" \ -d '{"connectorTypes":[]}'Parameters
Section titled “Parameters”| Name | In | Required | Type | Description |
|---|---|---|---|---|
auditId | path | yes | string | The audit’s id. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
connectorTypes | “OPENAI” | “OPENAI_GPT” | “GOOGLE_AI_OVERVIEW” | “GOOGLE_AI_MODE” | “PERPLEXITY” | “COPILOT” | “CLAUDE” | “GEMINI_APP” | “CHATGPT_APP” | “XAI_GROK”[] | yes | |
model | string | ||
languages | string[] | ||
locations | string[] | ||
angleIds | string[] | ||
snapshotTimeZone | string | An IANA time zone, e.g. “America/Toronto”; anything else is refused. |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object | yes | |
data.auditId | string | yes | |
data.estimate | object | Estimated run size — query and execution counts. | |
data.effectiveConnectors | string[] | ||
data.droppedConnectors | string[] |