Audits
An audit is one measurement target plus its configuration. Create one, configure it, then start a run. Beta: these shapes may change; see the changelog.
List audits
Section titled “List audits”GET /audits
Your organization’s audits, newest first, cursor-paginated. Note that nextCursor sits BESIDE data, not inside it: pass it back as ?cursor= to fetch the next page, and stop when it is null. Scores are null until the audit has produced a snapshot.
curl "https://api.beket.ai/api/v1/audits?cursor=CURSOR&take=TAKE" \ -H "Authorization: Bearer $BEKET_API_KEY"Parameters
Section titled “Parameters”| Name | In | Required | Type | Description |
|---|---|---|---|---|
cursor | query | no | string | Opaque cursor from a previous response’s nextCursor. |
take | query | no | integer | Page size. Defaults to 50, capped at 100. |
domain | query | no | string | Only audits of this domain. |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object[] | yes | |
data[].id | string | yes | |
data[].url | string | null | ||
data[].status | string | yes | |
data[].mode | string | ||
data[].brandName | string | null | ||
data[].faviconUrl | string | null | ||
data[].aeoScore | number | null | ||
data[].sovScore | number | null | ||
data[].snapshotEnabled | boolean | ||
data[].createdAt | string | ||
data[].updatedAt | string | ||
nextCursor | string | null |
Example response (200)
Section titled “Example response (200)”{ "success": true, "data": [ { "id": "clrecorderaudit0000000001", "url": "example.com", "status": "COMPLETED", "mode": "brand", "brandName": "Example Co", "subjectPath": null, "subjectLabel": "Example Co", "faviconUrl": null, "visibility": 62, "sovScore": null, "snapshotEnabled": true, "createdAt": "2026-10-26T19:53:04.847Z", "updatedAt": "2026-10-26T19:53:04.847Z", "lastRunAt": "2026-10-25T19:53:04.851Z", "cancelledAt": null, "cancelsAt": null } ], "nextCursor": null}Create an audit
Section titled “Create an audit”POST /audits
Four ways to name the target, in one of four request shapes: an existing entityId, a domain (an entity is resolved or created for it), a topic for a market-mode audit, or an inline profile when you already know the brand details. The audit is created in a pending state — it does not begin measuring until you start a run.
curl -X POST "https://api.beket.ai/api/v1/audits" \ -H "Authorization: Bearer $BEKET_API_KEY" \ -H "Content-Type: application/json" \ -d '{"entityId":"<entityId>"}'Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object | yes | |
data.auditId | string | yes | |
data.entityId | string | null | ||
data.status | string | yes |
Get an audit
Section titled “Get an audit”GET /audits/{auditId}
The audit with its entity, profile, and angles. A request for an audit belonging to another organization returns 404, not 403 — the API does not confirm that it exists.
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID" \ -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.id | string | yes | |
data.url | string | null | ||
data.status | string | yes | |
data.error | string | null | ||
data.createdAt | string | ||
data.updatedAt | string | ||
data.entity | object | null | ||
data.entity.id | string | ||
data.entity.domain | string | null | ||
data.entity.name | string | null | ||
data.entity.category | string | null | ||
data.profile | object | null | The brand profile. Field set depends on how the audit was created and what discovery found. | |
data.angles | object[] | ||
data.angles[].id | string | ||
data.angles[].name | string | ||
data.synthesis | object | null | ||
data.synthesis.available | boolean | yes | |
data.synthesis.createdAt | string | yes |
Example response (200)
Section titled “Example response (200)”{ "success": true, "data": { "id": "clrecorderaudit0000000001", "url": "example.com", "subjectPath": null, "status": "COMPLETED", "error": null, "createdAt": "2026-10-26T19:53:04.847Z", "updatedAt": "2026-10-26T19:53:04.847Z", "entity": { "id": "clrecorderentity000000001", "domain": "example.com", "name": "Example Co", "category": "SOFTWARE", "faviconUrl": null, "ogImageUrl": null }, "profile": { "brandName": "Example Co", "category": null, "description": "A fixture brand.", "competitors": null, "differentiators": null, "icp": null }, "angles": [ { "angleId": "BRAND_DISCOVERY", "status": "COMPLETED", "error": null, "updatedAt": "2026-10-26T19:53:04.854Z" }, { "angleId": "CUSTOM", "status": "PENDING", "error": null, "updatedAt": "2026-10-26T19:53:04.914Z" } ], "synthesis": null }}Get configuration options for an audit
Section titled “Get configuration options for an audit”GET /audits/{auditId}/config-options
What this audit may be configured with, given the organization’s plan: selectable connectors, the connector ceiling, available languages and service areas, the angle list, and the inputs used to estimate a run’s size. Read this before starting a run — the ceiling is plan-dependent, and a selection above it is clamped rather than rejected.
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/config-options" \ -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.ready | boolean | yes | |
data.status | string | yes | |
data.availableConnectors | object[] | ||
data.availableConnectors[].type | string | yes | |
data.availableConnectors[].label | string | yes | |
data.availableConnectors[].supportsModel | boolean | ||
data.availableConnectors[].allowedModels | string[] | ||
data.availableConnectors[].supportsLocation | boolean | ||
data.availableConnectors[].supportsWebSearch | boolean | ||
data.availableConnectors[].isCheapDefault | boolean | ||
data.connectorSelectability | ConnectorSelectability | ||
data.maxConnectors | integer | ||
data.languages | string[] | ||
data.serviceAreas | string[] | ||
data.angles | object[] | ||
data.angles[].id | string | ||
data.angles[].name | string | ||
data.estimateInputs | object | ||
data.estimateInputs.angleCount | integer | ||
data.estimateInputs.queriesPerAngle | integer | ||
data.estimateInputs.maxExecutions | integer |
Example response (200)
Section titled “Example response (200)”{ "success": true, "data": { "ready": false, "status": "COMPLETED", "availableConnectors": [ { "type": "CHATGPT_APP", "label": "ChatGPT", "supportsModel": false, "allowedModels": [], "supportsLocation": true, "supportsWebSearch": true, "dotColor": "#000000", "isCheapDefault": false }, { "type": "GOOGLE_AI_OVERVIEW", "label": "AI Overview", "supportsModel": false, "allowedModels": [], "supportsLocation": true, "supportsWebSearch": true, "dotColor": "#f59e0b", "isCheapDefault": false } ], "connectorSelectability": [ { "type": "CHATGPT_APP", "label": "ChatGPT", "locked": false, "preselected": true, "reason": "ok" }, { "type": "GOOGLE_AI_OVERVIEW", "label": "AI Overview", "locked": false, "preselected": true, "reason": "ok" } ], "maxConnectors": 5, "languages": [ "EN" ], "serviceAreas": [], "angles": [ { "angleId": "BRAND_DISCOVERY", "label": "Brand Discovery", "querySubjects": [ "CATEGORY" ] }, { "angleId": "CUSTOM", "label": "Custom", "querySubjects": [] } ], "estimateInputs": { "angleCount": 2, "queriesPerAngle": 4, "maxExecutions": 3500 } }}Get an audit’s selected connectors
Section titled “Get an audit’s selected connectors”GET /audits/{auditId}/connectors
Which AI surfaces this audit queries, plus the plan’s per-connector selectability and ceiling. connectorTypes is the current selection; selectability explains why a connector is or is not available to this organization.
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/connectors" \ -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 | ConnectorSelection | yes |
Example response (200)
Section titled “Example response (200)”{ "success": true, "data": { "connectorTypes": [], "selectability": [ { "type": "CHATGPT_APP", "label": "ChatGPT", "locked": false, "preselected": true, "reason": "ok" }, { "type": "GOOGLE_AI_OVERVIEW", "label": "AI Overview", "locked": false, "preselected": true, "reason": "ok" } ], "maxConnectors": 5 }}Replace an audit’s selected connectors
Section titled “Replace an audit’s selected connectors”PATCH /audits/{auditId}/connectors
Sets which AI surfaces this audit queries. The selection is clamped to the plan’s ceiling rather than rejected — read maxConnectors back from the response to see what was actually kept. Returns 409 while the audit is in a state where its configuration is not editable (mid-run, for instance), so check the audit’s status first.
curl -X PATCH "https://api.beket.ai/api/v1/audits/AUDIT_ID/connectors" \ -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 |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | ConnectorSelection | yes |
Example response (200)
Section titled “Example response (200)”{ "success": true, "data": { "connectorTypes": [ "CHATGPT_APP" ], "selectability": [ { "type": "CHATGPT_APP", "label": "ChatGPT", "locked": false, "preselected": true, "reason": "ok" }, { "type": "GOOGLE_AI_OVERVIEW", "label": "AI Overview", "locked": false, "preselected": true, "reason": "ok" } ], "maxConnectors": 5 }}Prepare a newly created audit
Section titled “Prepare a newly created audit”POST /audits/{auditId}/prepare
The required second step. A new audit is created PENDING, which is not yet a state anything can be generated or run from: it has no brand profile, and prompts are generated from that profile. Preparing explores the target, infers the profile, and selects the angles, moving the audit PENDING → PREPARING → AWAITING_CONFIG.
This is asynchronous. It answers 202 and returns immediately; the work happens on a queue. Poll GET /audits/{auditId} and wait for status to reach AWAITING_CONFIG before calling POST /audits/{auditId}/prompts/generate or POST /audits/{auditId}/start — both reject a PENDING or PREPARING audit with a 409.
This costs money — it crawls the target and runs an LLM to infer the profile. Calling it twice while a prepare is already queued or running is a no-op rather than a second run of the work, but do not re-prepare an audit that is past PENDING: that redoes the exploration and clobbers configuration you have already set.
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/prepare" \ -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.jobId | string | null |
Get an audit’s brand profile
Section titled “Get an audit’s brand profile”GET /audits/{auditId}/profile
The profile the prompts are generated from. Returns an empty profile object rather than 404 when none has been extracted yet, so a client can render the form either way.
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/profile" \ -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.profile | object | yes | Brand profile fields — name, category, description, products, competitors. |
Example response (200)
Section titled “Example response (200)”{ "success": true, "data": { "profile": { "brandName": "Example Co", "brandAliases": [], "primaryProduct": "Widgets", "offer": "Widgets that work", "description": "A fixture brand.", "icp": [], "differentiators": [], "painPoints": [], "vertical": null, "categoryLabel": null, "segment": null, "marketScope": null, "city": null, "serviceRadius": null, "anchors": null, "neutralDescription": null, "painPrompts": [], "verifiedClaims": [] }, "claimsSeeded": true }}Replace an audit’s brand profile
Section titled “Replace an audit’s brand profile”PATCH /audits/{auditId}/profile
Overwrites the editable profile fields — send the whole object, not a partial patch, because absent nullable fields are written as null. Free-text list fields are trimmed, de-duplicated, and blank entries dropped rather than rejected.
One rule the schema below cannot express: categoryLabel must say what the brand does, not how it ranks — “commercial cleaning” is accepted, “best” is rejected with a 400. (It is enforced by a zod refinement, and refinements have no JSON Schema equivalent.)
The audit must have an entity; a market-mode audit with no owned domain returns 400.
curl -X PATCH "https://api.beket.ai/api/v1/audits/AUDIT_ID/profile" \ -H "Authorization: Bearer $BEKET_API_KEY" \ -H "Content-Type: application/json" \ -d '{"brandName":"<brandName>","brandAliases":[],"icp":[],"differentiators":[],"painPoints":[]}'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 |
|---|---|---|---|
brandName | string | yes | |
brandAliases | string[] | yes | |
primaryProduct | string | null | ||
offer | string | null | ||
description | string | null | ||
icp | string[] | yes | |
differentiators | string[] | yes | |
painPoints | string[] | yes | |
vertical | string | null | ||
categoryLabel | string | null | What the business does, e.g. “commercial cleaning”. A label that only ranks (“best”, “top”) is refused. | |
segment | string | null | ||
marketScope | “local” | “regional” | “national” | “online” | null | ||
city | string | null | ||
serviceRadius | string | null | ||
anchors | object | null | ||
verifiedClaims | object[] | ||
verifiedClaims[].text | string | yes | |
verifiedClaims[].verified | boolean | ||
neutralDescription | string | null | ||
painPrompts | object[] | ||
painPrompts[].text | string | yes | |
painPrompts[].promptEN | string | yes | |
painPrompts[].promptFR | string | null | ||
painPrompts[].on | boolean |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object | yes | |
data.profile | object | yes | The profile as persisted. |
Example response (200)
Section titled “Example response (200)”{ "success": true, "data": { "profile": { "brandName": "Example Co", "brandAliases": [], "primaryProduct": "Widgets", "offer": "Widgets that work", "description": "A fixture brand.", "icp": [ "Operations teams" ], "differentiators": [], "painPoints": [], "vertical": null, "categoryLabel": "widget software", "segment": null, "marketScope": null, "city": null, "serviceRadius": null, "anchors": null, "neutralDescription": null, "painPrompts": [], "verifiedClaims": [] }, "claimsSeeded": true }}Schemas
Section titled “Schemas”ConnectorSelectability
Section titled “ConnectorSelectability”| Field | Type | Required | Description |
|---|---|---|---|
[].type | string | yes | |
[].label | string | yes | |
[].locked | boolean | yes | |
[].preselected | boolean | yes | |
[].reason | “ok” | “plan_pinned” | “over_cap” | yes |
ConnectorSelection
Section titled “ConnectorSelection”| Field | Type | Required | Description |
|---|---|---|---|
connectorTypes | string[] | yes | |
selectability | ConnectorSelectability | ||
maxConnectors | integer |