Skip to content

Results

What the audit measured: metrics, the report, and the snapshot history. Beta: these shapes may change; see the changelog.

GET /analytics/portfolio

Totals across every audit in your organization, aggregated in the database rather than assembled client-side. Bounded by design: it returns portfolio totals and at most ten competitors. For per-audit detail, use the single-audit endpoints — this one will not grow to carry it.

Terminal window
curl "https://api.beket.ai/api/v1/analytics/portfolio?entityId=ENTITY_ID&domain=DOMAIN" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
entityIdquerynostringRestrict the roll-up to one entity.
domainquerynostringRestrict the roll-up to one domain.
takequerynointegerHow many audits to aggregate. Defaults to 50, capped at 200.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.auditCountintegeryes
data.aggregatesobjectyes
data.aggregates.totalMentionsintegeryes
data.aggregates.totalWinnableQueriesintegeryes
data.aggregates.topCompetitorsobject[]yes
data.aggregates.topCompetitors[].namestringyes
data.aggregates.topCompetitors[].mentionsnumberyes
{
"success": true,
"data": {
"auditCount": 1,
"aggregates": {
"totalMentions": 0,
"totalWinnableQueries": 0,
"topCompetitors": []
}
}
}

GET /audits/{auditId}/answers/export

Every answer received between from and to, one row each, newest first — the raw material behind the report. Pages hold up to 5000 rows; pass nextCursor back as cursor until it is null. A range spans at most 366 days.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/answers/export?from=FROM&to=TO" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
fromqueryyesstringFirst day of answers to include, YYYY-MM-DD (UTC).
toqueryyesstringLast day to include, YYYY-MM-DD (UTC). At most 366 days after from.
cursorquerynostringOpaque cursor from a previous page’s nextCursor.
limitquerynointegerRows per page.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.rowsobject[]yes
data.rows[].answerIdstringyes
data.rows[].runAtstringyesWhen the answer was received, UTC.
data.rows[].snapshotIdstring | nullyesThe earliest snapshot holding this answer; null until one does.
data.rows[].promptstringyes
data.rows[].promptType“UNBRANDED” | “BRANDED” | “RECALL”yes
data.rows[].topicstring | nullyes
data.rows[].anglestring | nullyes
data.rows[].firstPartySource“ads_csv” | “ads_api” | “gsc” | nullyes
data.rows[].firstPartyTermstring | nullyes
data.rows[].enginestring | nullyesThe connector that asked, e.g. OPENAI.
data.rows[].lanestringyesWhat was measured, e.g. CHATGPT or CHATGPT:gpt-5.
data.rows[].mentionedboolean | nullyes
data.rows[].positioninteger | nullyes
data.rows[].citationCountinteger | nullyes
data.rows[].brandCitationCountinteger | nullyes
data.rows[].sentimentnumber | nullyesSentiment of the sentences naming the brand, 0–1.
data.rows[].offTopicbooleanyesThe report leaves this answer out of its counts.
data.nextCursorstring | nullyes
{
"success": true,
"data": {
"rows": [
{
"answerId": "clrecorderanswer000000001",
"runAt": "2026-10-25T19:53:04.860Z",
"snapshotId": null,
"prompt": "what is the best widget software",
"promptType": "UNBRANDED",
"topic": null,
"angle": "Brand Discovery",
"firstPartySource": null,
"firstPartyTerm": null,
"engine": "OPENAI",
"lane": "OPENAI",
"mentioned": null,
"position": null,
"citationCount": null,
"brandCitationCount": null,
"sentiment": null,
"offTopic": false
}
],
"nextCursor": null
}
}

GET /audits/{auditId}/answers/export.csv

The same rows as GET /audits/{auditId}/answers/export, as a CSV download with snake_case headers. Past 10000 rows the file ends with a # truncated line and the X-Beket-Truncated header is set; page the JSON export for the rest.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/answers/export.csv?from=FROM&to=TO" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
fromqueryyesstringFirst day of answers to include, YYYY-MM-DD (UTC).
toqueryyesstringLast day to include, YYYY-MM-DD (UTC). At most 366 days after from.

POST /audits/{auditId}/metrics/compute

Recomputes the metrics from the stored answers without rewriting the report or asking the AI surfaces again, and costs nothing. Answers 202; poll GET /audits/{auditId}/synthesis until the status is back to COMPLETED. A market audit rebuilds through POST /audits/{auditId}/synthesis/regenerate instead.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/metrics/compute" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataRecomputeJobyes

GET /audits/{auditId}/optimizations/progress

What moved since the baseline: the newest snapshot taken against a baseline (or the one snapshotId names), diffed against that baseline, plus every winnable prompt of the pair, changed or not. diff is null and allWinnableQueries empty until a snapshot names a baseline. Send the ETag back as If-None-Match to get a 304 while nothing changed.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/optimizations/progress?snapshotId=SNAPSHOT_ID" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
snapshotIdquerynostringThe snapshot to read. Omit it for the newest snapshot taken against a baseline.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.latestSnapshotIdstring | nullyes
data.baselineSnapshotIdstring | nullyes
data.diffSnapshotDiff | nullyes
data.allWinnableQueriesobject[]yes

GET /audits/{auditId}/snapshots

The snapshot history, newest first, cursor-paginated — the cheapest way to watch an audit over time, and the right endpoint to poll. Each item carries summary metrics and reportAvailable, which tells you whether that snapshot can hydrate a report. The per-segment overviewCube is the one heavy field and is omitted unless you ask for it with ?include=overviewCube, which keeps a page bounded. Note the response sets Cache-Control: private, no-store, because it includes mutable state (the snapshot pause toggle and manual-run eligibility).

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/snapshots?limit=LIMIT&order=ORDER" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
limitquerynointegerPage size. Defaults to 50, capped at 200.
orderqueryno“desc” | “asc”Newest first (desc, the default) or oldest first (asc).
includequerynostringComma-separated heavy fields to include: overviewCube.
cursorquerynostringOpaque cursor from a previous response’s nextCursor.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.snapshotsobject[]yes
data.snapshots[].idstringyes
data.snapshots[].labelstring | null
data.snapshots[].type“full” | “short”yes
data.snapshots[].createdAtstringyes
data.snapshots[].connectorTypesstring[]
data.snapshots[].alertsarray | null
data.snapshots[].metricsobject | nullSummary metrics for this snapshot.
data.snapshots[].durationMsinteger | null
data.snapshots[].reportAvailablebooleanyes
data.nextCursorstring | nullyes
data.scheduleobject | null
data.schedule.intervalHoursinteger | null
data.schedule.nextRunAtstring | null
data.schedule.snapshotEnabledboolean
data.scheduleAvailableboolean
data.manualRunobject | null
data.manualRun.eligibleboolean
data.manualRun.nextEligibleAtstring | null
data.manualRun.reason“ok” | “cooldown” | “auto_plan” | “period_run_cap”
{
"success": true,
"data": {
"snapshots": [
{
"id": "00000000-0000-4000-8000-00000000e102",
"label": null,
"type": "full",
"createdAt": "2026-10-25T19:53:04.851Z",
"connectorTypes": [],
"metrics": {
"ccrScore": 0.4,
"overview": {
"visibility": 0.62
},
"sbaScore": 0.5,
"marketTrend": null,
"shareOfVoice": [
{
"name": "…",
"share": "…",
"isBrand": "…"
},
{
"name": "…",
"share": "…",
"isBrand": "…"
}
],
"visibilityScore": 0.62,
"brandMentionCount": 12,
"visibilityCompetitors": null
},
"durationMs": null,
"reportAvailable": true,
"alerts": null
},
{
"id": "00000000-0000-4000-8000-00000000e101",
"label": null,
"type": "full",
"createdAt": "2026-10-18T19:53:04.849Z",
"connectorTypes": [],
"metrics": {
"ccrScore": 0.4,
"overview": {
"visibility": 0.62
},
"sbaScore": 0.5,
"marketTrend": null,
"shareOfVoice": [
{
"name": "…",
"share": "…",
"isBrand": "…"
},
{
"name": "…",
"share": "…",
"isBrand": "…"
}
],
"visibilityScore": 0.62,
"brandMentionCount": 12,
"visibilityCompetitors": null
},
"durationMs": null,
"reportAvailable": false,
"alerts": null
}
],
"nextCursor": null,
"schedule": null,
"scheduleAvailable": true,
"manualRun": {
"eligible": false,
"nextEligibleAt": null,
"reason": "auto_plan"
},
"forcedRunAvailable": true
}
}

POST /audits/{auditId}/snapshots

Freezes the audit’s current results as a snapshot, to compare against later — before a site change, say. Asks no AI surface; it records what the last run measured. baselineSnapshotId names the snapshot a later compare measures it against.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/snapshots" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"label":"<label>"}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
labelstring
baselineSnapshotIdstringThe id of an earlier snapshot of this audit (a UUID, or a legacy cuid) that a compare with a omitted measures this one against. Omit it for no baseline.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.snapshotIdstringyes

GET /audits/{auditId}/snapshots/{snapshotId}/alerts

The changes a snapshot raised against the one before it — a new competitor, a metric delta, a rank move, a blocked crawler — at most 80. Each type carries its own fields. A snapshot’s alerts never change once written.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/snapshots/SNAPSHOT_ID/alerts" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
snapshotIdpathyesstringThe snapshot’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.auditIdstringyes
data.auditLabelstringyes
data.snapshotIdstringyes
data.createdAtstringyes
data.alertsobject[]yes
data.alerts[].type“new_competitor” | “entity_disappeared” | “new_citation_source” | “metric_delta” | “rank_move” | “striking_distance_entry” | “ai_referral_delta” | “edge_blocked_crawler”yes
data.alerts[].entityNamestring
data.alerts[].domainstring
data.alerts[].metricstring
data.alerts[].beforenumber | null
data.alerts[].afternumber | null
data.alerts[].deltanumber
data.alerts[].keywordstring
data.alerts[].tier“almost_there” | “page_two”
data.alerts[].botstring
data.alerts[].requestsinteger
data.alerts[].blockedRequestsinteger
data.alerts[].basis“robots_contradiction” | “live_fetch_refused”
{
"success": true,
"data": {
"auditId": "clrecorderaudit0000000001",
"auditLabel": "example.com",
"snapshotId": "00000000-0000-4000-8000-00000000e102",
"createdAt": "2026-10-25T19:53:04.851Z",
"alerts": []
}
}

GET /audits/{auditId}/snapshots/compare

What moved between two snapshots of an audit: prompts, per-answer metrics, competitors, cited sources and the report’s recommendations. Omit a to compare b with the baseline it was taken against. The two longest lists are capped; their totals stay exact. Send the ETag back as If-None-Match to get a 304 while nothing changed.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/snapshots/compare?a=A&b=B" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
aquerynostringThe earlier snapshot. Omit it to compare b with its own baseline.
bquerynostringThe later snapshot.
FieldTypeRequiredDescription
successbooleanyes
dataSnapshotDiffyes

GET /audits/{auditId}/synthesis

The audit’s status and whether its written analysis exists yet — the cheap poll after a regenerate.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/synthesis" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.statusstringyes
data.llmbooleanyesThe written analysis exists.
{
"success": true,
"data": {
"status": "COMPLETED",
"llm": false
}
}

POST /audits/{auditId}/synthesis/regenerate

Recomputes the metrics from the stored answers and rewrites the report — after a change to competitors, say. No AI surface is asked again. A market audit rebuilds its leaderboard instead. Answers 202; poll GET /audits/{auditId}/synthesis. This starts paid work.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/synthesis/regenerate" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataRecomputeJobyes

POST /audits/{auditId}/synthesis/run

Writes the report’s analysis over the metrics the last run computed, without asking the AI surfaces again. Answers 202; poll GET /audits/{auditId}/synthesis. This starts paid work.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/synthesis/run" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.auditIdstringyes
data.statusstringyes
FieldTypeRequiredDescription
auditIdstringyes
statusstringyes
FieldTypeRequiredDescription
snapshotAstringyes
snapshotBstringyes
queryChangesobject[]yesAt most 500; see queryChangesTruncated.
queryChanges[].keystringyes
queryChanges[].type“added” | “removed” | “changed”yes
queryChanges[].beforeobjectThe prompt as frozen in snapshot A.
queryChanges[].afterobjectThe prompt as frozen in snapshot B.
queryChangeCountsobjectyesExact, including rows past the cap.
queryChangeCounts.addedintegeryes
queryChangeCounts.removedintegeryes
queryChangeCounts.changedintegeryes
queryChangesTruncatedbooleanyes
metricChangesobject[]yesOne row per metric per answer that moved. At most 5000; see metricChangesTruncated.
metricChanges[].keystringyes
metricChanges[].metricstringyes
metricChanges[].beforenumber | nullyes
metricChanges[].afternumber | nullyes
metricChanges[].deltanumber | nullyes
metricChangeCountsobjectyesExact totals per metric, including rows past the cap.
metricChangesTruncatedbooleanyes
competitorChangesobject[]yes
competitorChanges[].keystringyesDisplay name.
competitorChanges[].idstringyesThe identity the two sides were matched on.
competitorChanges[].domainstring | nullyes
competitorChanges[].beforeRankinteger | nullyes
competitorChanges[].afterRankinteger | nullyes
competitorChanges[].beforeMentionsinteger | nullyes
competitorChanges[].afterMentionsinteger | nullyes
sourceChangesobject[]yes
sourceChanges[].keystringyes
sourceChanges[].change“opened” | “closed”yes
sourceChanges[].beforeobjectThe source on side A.
sourceChanges[].afterobjectThe source on side B.
synthesisChangesobjectyes
synthesisChanges.winnableQueriesobject[]yes
synthesisChanges.contentRoadmapChangesobject[]yes
synthesisChanges.provenanceChangesobject[]yes
synthesisChanges.provenanceChanges[].keystringyes
synthesisChanges.provenanceChanges[].beforeDomainsstring[]yes
synthesisChanges.provenanceChanges[].afterDomainsstring[]yes
unavailableobjectyesInputs a side no longer has — archived or pruned. An empty facet over a missing input means “unknown”, not “unchanged”.
unavailable.astring[]yes
unavailable.bstring[]yes
comparablebooleanyesFalse when the two snapshots were measured under different conditions.
incomparableReason“model-change” | “backend-change” | “metrics-version-change” | “unknown-provenance”Absent when comparable is true.