Skip to content

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.

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.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/run" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.auditIdstringyes
data.runStatusstringyes
data.auditStatusstringyes
data.laneProgressobject | nullPer-lane progress counters. Present only while collecting.
data.startedAtstring | null
data.optionsobject | nullThe options the run was started with.
data.errorstring | null
data.updatedAtstring
data.retryAfterMsinteger | nullyes
{
"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
}
}

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.

Terminal window
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>"}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
domainstring
anglesstring[]
queriesPerAngleinteger
refreshAnswersboolean
forceRecoverboolean
connectorTypesstring[]
enrichCompetitorsboolean
crawlPolicy“skip” | “reuse_if_fresh” | “force_fresh”
crawlFreshnessMaxAgeDaysinteger
createSnapshotboolean
snapshotLabelstring
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.auditIdstringyes
data.statusstringyes
data.startedAtstring | null
data.optionsobjectThe options the run was started with, after clamping.

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.

Terminal window
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":[]}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
connectorTypes“OPENAI” | “OPENAI_GPT” | “GOOGLE_AI_OVERVIEW” | “GOOGLE_AI_MODE” | “PERPLEXITY” | “COPILOT” | “CLAUDE” | “GEMINI_APP” | “CHATGPT_APP” | “XAI_GROK”[]yes
modelstring
languagesstring[]
locationsstring[]
angleIdsstring[]
snapshotTimeZonestringAn IANA time zone, e.g. “America/Toronto”; anything else is refused.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.auditIdstringyes
data.estimateobjectEstimated run size — query and execution counts.
data.effectiveConnectorsstring[]
data.droppedConnectorsstring[]