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.
curl " https://api.beket.ai/api/v1/analytics/portfolio?entityId=ENTITY_ID&domain=DOMAIN " \
-H " Authorization: Bearer $BEKET_API_KEY "
Name In Required Type Description entityIdquery no string Restrict the roll-up to one entity. domainquery no string Restrict the roll-up to one domain. takequery no integer How many audits to aggregate. Defaults to 50, capped at 200.
Field Type Required Description successboolean yes dataobject yes data.auditCountinteger yes data.aggregatesobject yes data.aggregates.totalMentionsinteger yes data.aggregates.totalWinnableQueriesinteger yes data.aggregates.topCompetitorsobject[] yes data.aggregates.topCompetitors[].namestring yes data.aggregates.topCompetitors[].mentionsnumber yes
"totalWinnableQueries" : 0 ,
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.
curl " https://api.beket.ai/api/v1/audits/AUDIT_ID/answers/export?from=FROM&to=TO " \
-H " Authorization: Bearer $BEKET_API_KEY "
Name In Required Type Description auditIdpath yes string The audit’s id. fromquery yes string First day of answers to include, YYYY-MM-DD (UTC). toquery yes string Last day to include, YYYY-MM-DD (UTC). At most 366 days after from. cursorquery no string Opaque cursor from a previous page’s nextCursor. limitquery no integer Rows per page.
Field Type Required Description successboolean yes dataobject yes data.rowsobject[] yes data.rows[].answerIdstring yes data.rows[].runAtstring yes When the answer was received, UTC. data.rows[].snapshotIdstring | null yes The earliest snapshot holding this answer; null until one does. data.rows[].promptstring yes data.rows[].promptType“UNBRANDED” | “BRANDED” | “RECALL” yes data.rows[].topicstring | null yes data.rows[].anglestring | null yes data.rows[].firstPartySource“ads_csv” | “ads_api” | “gsc” | null yes data.rows[].firstPartyTermstring | null yes data.rows[].enginestring | null yes The connector that asked, e.g. OPENAI. data.rows[].lanestring yes What was measured, e.g. CHATGPT or CHATGPT:gpt-5. data.rows[].mentionedboolean | null yes data.rows[].positioninteger | null yes data.rows[].citationCountinteger | null yes data.rows[].brandCitationCountinteger | null yes data.rows[].sentimentnumber | null yes Sentiment of the sentences naming the brand, 0–1. data.rows[].offTopicboolean yes The report leaves this answer out of its counts. data.nextCursorstring | null yes
"answerId" : " clrecorderanswer000000001 " ,
"runAt" : " 2026-10-25T19:53:04.860Z " ,
"prompt" : " what is the best widget software " ,
"promptType" : " UNBRANDED " ,
"angle" : " Brand Discovery " ,
"firstPartySource" : null ,
"brandCitationCount" : 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.
curl " https://api.beket.ai/api/v1/audits/AUDIT_ID/answers/export.csv?from=FROM&to=TO " \
-H " Authorization: Bearer $BEKET_API_KEY "
Name In Required Type Description auditIdpath yes string The audit’s id. fromquery yes string First day of answers to include, YYYY-MM-DD (UTC). toquery yes string Last 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.
curl -X POST " https://api.beket.ai/api/v1/audits/AUDIT_ID/metrics/compute " \
-H " Authorization: Bearer $BEKET_API_KEY "
Name In Required Type Description auditIdpath yes string The audit’s id.
Field Type Required Description successboolean yes dataRecomputeJob yes
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.
curl " https://api.beket.ai/api/v1/audits/AUDIT_ID/optimizations/progress?snapshotId=SNAPSHOT_ID " \
-H " Authorization: Bearer $BEKET_API_KEY "
Name In Required Type Description auditIdpath yes string The audit’s id. snapshotIdquery no string The snapshot to read. Omit it for the newest snapshot taken against a baseline.
Field Type Required Description successboolean yes dataobject yes data.latestSnapshotIdstring | null yes data.baselineSnapshotIdstring | null yes 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).
curl " https://api.beket.ai/api/v1/audits/AUDIT_ID/snapshots?limit=LIMIT&order=ORDER " \
-H " Authorization: Bearer $BEKET_API_KEY "
Name In Required Type Description auditIdpath yes string The audit’s id. limitquery no integer Page size. Defaults to 50, capped at 200. orderquery no “desc” | “asc” Newest first (desc, the default) or oldest first (asc). includequery no string Comma-separated heavy fields to include: overviewCube. cursorquery no string Opaque cursor from a previous response’s nextCursor.
Field Type Required Description successboolean yes dataobject yes data.snapshotsobject[] yes data.snapshots[].idstring yes data.snapshots[].labelstring | null data.snapshots[].type“full” | “short” yes data.snapshots[].createdAtstring yes data.snapshots[].connectorTypesstring[] data.snapshots[].alertsarray | null data.snapshots[].metricsobject | null Summary metrics for this snapshot. data.snapshots[].durationMsinteger | null data.snapshots[].reportAvailableboolean yes data.nextCursorstring | null yes 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”
"id" : " 00000000-0000-4000-8000-00000000e102 " ,
"createdAt" : " 2026-10-25T19:53:04.851Z " ,
"visibilityCompetitors" : null
"id" : " 00000000-0000-4000-8000-00000000e101 " ,
"createdAt" : " 2026-10-18T19:53:04.849Z " ,
"visibilityCompetitors" : null
"reportAvailable" : false ,
"scheduleAvailable" : true ,
"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.
curl -X POST " https://api.beket.ai/api/v1/audits/AUDIT_ID/snapshots " \
-H " Authorization: Bearer $BEKET_API_KEY " \
-H " Content-Type: application/json " \
Name In Required Type Description auditIdpath yes string The audit’s id.
Field Type Required Description labelstring baselineSnapshotIdstring The 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.
Field Type Required Description successboolean yes dataobject yes data.snapshotIdstring yes
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.
curl " https://api.beket.ai/api/v1/audits/AUDIT_ID/snapshots/SNAPSHOT_ID/alerts " \
-H " Authorization: Bearer $BEKET_API_KEY "
Name In Required Type Description auditIdpath yes string The audit’s id. snapshotIdpath yes string The snapshot’s id.
Field Type Required Description successboolean yes dataobject yes data.auditIdstring yes data.auditLabelstring yes data.snapshotIdstring yes data.createdAtstring yes 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”
"auditId" : " clrecorderaudit0000000001 " ,
"auditLabel" : " example.com " ,
"snapshotId" : " 00000000-0000-4000-8000-00000000e102 " ,
"createdAt" : " 2026-10-25T19:53:04.851Z " ,
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.
curl " https://api.beket.ai/api/v1/audits/AUDIT_ID/snapshots/compare?a=A&b=B " \
-H " Authorization: Bearer $BEKET_API_KEY "
Name In Required Type Description auditIdpath yes string The audit’s id. aquery no string The earlier snapshot. Omit it to compare b with its own baseline. bquery no string The later snapshot.
Field Type Required Description successboolean yes dataSnapshotDiff yes
GET /audits/{auditId}/synthesis
The audit’s status and whether its written analysis exists yet — the cheap poll after a regenerate.
curl " https://api.beket.ai/api/v1/audits/AUDIT_ID/synthesis " \
-H " Authorization: Bearer $BEKET_API_KEY "
Name In Required Type Description auditIdpath yes string The audit’s id.
Field Type Required Description successboolean yes dataobject yes data.statusstring yes data.llmboolean yes The written analysis exists.
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.
curl -X POST " https://api.beket.ai/api/v1/audits/AUDIT_ID/synthesis/regenerate " \
-H " Authorization: Bearer $BEKET_API_KEY "
Name In Required Type Description auditIdpath yes string The audit’s id.
Field Type Required Description successboolean yes dataRecomputeJob yes
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.
curl -X POST " https://api.beket.ai/api/v1/audits/AUDIT_ID/synthesis/run " \
-H " Authorization: Bearer $BEKET_API_KEY "
Name In Required Type Description auditIdpath yes string The audit’s id.
Field Type Required Description successboolean yes dataobject yes data.auditIdstring yes data.statusstring yes
Field Type Required Description auditIdstring yes statusstring yes
Field Type Required Description snapshotAstring yes snapshotBstring yes queryChangesobject[] yes At most 500; see queryChangesTruncated. queryChanges[].keystring yes queryChanges[].type“added” | “removed” | “changed” yes queryChanges[].beforeobject The prompt as frozen in snapshot A. queryChanges[].afterobject The prompt as frozen in snapshot B. queryChangeCountsobject yes Exact, including rows past the cap. queryChangeCounts.addedinteger yes queryChangeCounts.removedinteger yes queryChangeCounts.changedinteger yes queryChangesTruncatedboolean yes metricChangesobject[] yes One row per metric per answer that moved. At most 5000; see metricChangesTruncated. metricChanges[].keystring yes metricChanges[].metricstring yes metricChanges[].beforenumber | null yes metricChanges[].afternumber | null yes metricChanges[].deltanumber | null yes metricChangeCountsobject yes Exact totals per metric, including rows past the cap. metricChangesTruncatedboolean yes competitorChangesobject[] yes competitorChanges[].keystring yes Display name. competitorChanges[].idstring yes The identity the two sides were matched on. competitorChanges[].domainstring | null yes competitorChanges[].beforeRankinteger | null yes competitorChanges[].afterRankinteger | null yes competitorChanges[].beforeMentionsinteger | null yes competitorChanges[].afterMentionsinteger | null yes sourceChangesobject[] yes sourceChanges[].keystring yes sourceChanges[].change“opened” | “closed” yes sourceChanges[].beforeobject The source on side A. sourceChanges[].afterobject The source on side B. synthesisChangesobject yes synthesisChanges.winnableQueriesobject[] yes synthesisChanges.contentRoadmapChangesobject[] yes synthesisChanges.provenanceChangesobject[] yes synthesisChanges.provenanceChanges[].keystring yes synthesisChanges.provenanceChanges[].beforeDomainsstring[] yes synthesisChanges.provenanceChanges[].afterDomainsstring[] yes unavailableobject yes Inputs 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 comparableboolean yes False when the two snapshots were measured under different conditions. incomparableReason“model-change” | “backend-change” | “metrics-version-change” | “unknown-provenance” Absent when comparable is true.