Skip to content

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.

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.

Terminal window
curl "https://api.beket.ai/api/v1/audits?cursor=CURSOR&take=TAKE" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
cursorquerynostringOpaque cursor from a previous response’s nextCursor.
takequerynointegerPage size. Defaults to 50, capped at 100.
domainquerynostringOnly audits of this domain.
FieldTypeRequiredDescription
successbooleanyes
dataobject[]yes
data[].idstringyes
data[].urlstring | null
data[].statusstringyes
data[].modestring
data[].brandNamestring | null
data[].faviconUrlstring | null
data[].aeoScorenumber | null
data[].sovScorenumber | null
data[].snapshotEnabledboolean
data[].createdAtstring
data[].updatedAtstring
nextCursorstring | null
{
"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
}

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.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"entityId":"<entityId>"}'
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.auditIdstringyes
data.entityIdstring | null
data.statusstringyes

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.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.idstringyes
data.urlstring | null
data.statusstringyes
data.errorstring | null
data.createdAtstring
data.updatedAtstring
data.entityobject | null
data.entity.idstring
data.entity.domainstring | null
data.entity.namestring | null
data.entity.categorystring | null
data.profileobject | nullThe brand profile. Field set depends on how the audit was created and what discovery found.
data.anglesobject[]
data.angles[].idstring
data.angles[].namestring
data.synthesisobject | null
data.synthesis.availablebooleanyes
data.synthesis.createdAtstringyes
{
"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 /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.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/config-options" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.readybooleanyes
data.statusstringyes
data.availableConnectorsobject[]
data.availableConnectors[].typestringyes
data.availableConnectors[].labelstringyes
data.availableConnectors[].supportsModelboolean
data.availableConnectors[].allowedModelsstring[]
data.availableConnectors[].supportsLocationboolean
data.availableConnectors[].supportsWebSearchboolean
data.availableConnectors[].isCheapDefaultboolean
data.connectorSelectabilityConnectorSelectability
data.maxConnectorsinteger
data.languagesstring[]
data.serviceAreasstring[]
data.anglesobject[]
data.angles[].idstring
data.angles[].namestring
data.estimateInputsobject
data.estimateInputs.angleCountinteger
data.estimateInputs.queriesPerAngleinteger
data.estimateInputs.maxExecutionsinteger
{
"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 /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.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/connectors" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataConnectorSelectionyes
{
"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
}
}

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.

Terminal window
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":[]}'
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
FieldTypeRequiredDescription
successbooleanyes
dataConnectorSelectionyes
{
"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
}
}

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.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/prepare" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.auditIdstringyes
data.jobIdstring | null

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.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/profile" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.profileobjectyesBrand profile fields — name, category, description, products, competitors.
{
"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
}
}

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.

Terminal window
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":[]}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
brandNamestringyes
brandAliasesstring[]yes
primaryProductstring | null
offerstring | null
descriptionstring | null
icpstring[]yes
differentiatorsstring[]yes
painPointsstring[]yes
verticalstring | null
categoryLabelstring | nullWhat the business does, e.g. “commercial cleaning”. A label that only ranks (“best”, “top”) is refused.
segmentstring | null
marketScope“local” | “regional” | “national” | “online” | null
citystring | null
serviceRadiusstring | null
anchorsobject | null
verifiedClaimsobject[]
verifiedClaims[].textstringyes
verifiedClaims[].verifiedboolean
neutralDescriptionstring | null
painPromptsobject[]
painPrompts[].textstringyes
painPrompts[].promptENstringyes
painPrompts[].promptFRstring | null
painPrompts[].onboolean
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.profileobjectyesThe profile as persisted.
{
"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
}
}
FieldTypeRequiredDescription
[].typestringyes
[].labelstringyes
[].lockedbooleanyes
[].preselectedbooleanyes
[].reason“ok” | “plan_pinned” | “over_cap”yes
FieldTypeRequiredDescription
connectorTypesstring[]yes
selectabilityConnectorSelectability
maxConnectorsinteger