Skip to content

Reading the report

The report is read through GraphQL, one section at a time. You name the fields you want and the server reads only those from the database, so a summary costs a summary’s worth of transfer rather than the whole report.

Everything else in this API is REST. The report is the exception because it is large and heterogeneous: no single REST shape fits both “the headline numbers” and “page 3 of the winnable prompts”.

POST https://api.beket.ai/graphql

Note the path: /graphql sits at the API’s origin, not under /api/v1. It takes the same bkt_ key as every REST endpoint, sent the same way.

Terminal window
curl -X POST "https://api.beket.ai/graphql" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "query ($auditId: String!) { reportOverview(auditId: $auditId) { brandName synthesizedAt } }", "variables": {"auditId": "AUDIT_ID"}}'

A section is available once the audit’s report is written: GET /audits/{auditId}/synthesis answers llm: true. Until then each section below answers null.

You wantQueryAudit mode
Headline metrics, summary, key findingsreportOverviewbrand
Unprompted recall and the per-engine visibility gapreportVisibilityMetricsbrand
The prompts you could win, pagedreportWinnableQueriesbrand
The content roadmap and off-site opportunitiesreportRoadmapbrand
The market leaderboardmarketReportmarket

An audit’s mode is on each item of GET /audits. A brand-mode section asked of a market audit — or the other way round — answers null, the same as a report that is not written yet.

Only the fields on this page are covered by the changelog. The schema carries more, for the dashboard; those can change without notice.

The headline numbers and the written summary. One request, a few kilobytes.

query ReportSummary($auditId: String!) {
reportOverview(auditId: $auditId) {
auditId
brandName
domain
synthesizedAt
engines
executiveSummary
headline {
visibility
shareOfVoice
avgPosition
citationShare
sentiment
competitors { name visibility avgPosition }
}
keyFindings { title section impact }
}
reportVisibilityMetrics(auditId: $auditId) {
aiVisibilityGap {
verdict
answerCoverage
selfCitationShare
byEngine { connectorType answerCoverage brandAnswerCount totalAnswers }
}
}
}

The prompts where the brand is closest to being named, best first. Paged: limit defaults to 25 and is capped at 50. Pass byPrompt: true so one item is one prompt, whichever engines asked it.

query WinnablePrompts($auditId: String!, $limit: Int, $offset: Int) {
reportWinnableQueries(auditId: $auditId, limit: $limit, offset: $offset, byPrompt: true) {
totalCount
hasMore
offset
winnableQueries {
queryUuid
queryText
funnelStage
winScore
brandMentioned
topCompetitors
suggestedContentType
}
}
}

Read the next page by passing offset + limit while hasMore is true.

The pieces the report recommends writing, in order, and the third-party sites worth engaging. A roadmap piece’s position in contentRoadmap, counting from 0, is the contentPieceIndex that generating a content brief takes.

query Roadmap($auditId: String!) {
reportRoadmap(auditId: $auditId) {
status
contentRoadmap {
title
format
funnelStage
priority
rationale
targetQueryPrompts { queryUuid text }
}
engagementOpportunities {
domain
sourceType
suggestedAction
priority
}
}
}

For a market-mode audit: who AI surfaces name for the topic, ranked. Pass snapshotId to read the leaderboard as it stood at an earlier snapshot; omit it for the latest.

query MarketLeaderboard($auditId: String!, $snapshotId: String) {
marketReport(auditId: $auditId, snapshotId: $snapshotId) {
playerCount
leaderboard {
rank
competitorName
share
totalMentions
byEngine { connectorType totalMentions }
}
}
}

GraphQL answers most failures with HTTP 200 and an errors array, not with a REST status and the error envelope. Check errors on every response, not only the status.

ResponseMeaningWhat to do
data.<section> is null, no errorsNo report for this audit yet, or the wrong audit mode for this section.Check GET /audits/{auditId}/synthesis and the audit’s mode.
200, errors[].extensions.code = UNAUTHENTICATEDThe key is missing, revoked or expired.Check the key.
200, errors[].extensions.code = UNAUTHORIZEDThe audit belongs to another organization, or does not exist.Check the id and which organization the key belongs to.
402, errors[].extensions.code = PAYMENT_REQUIREDThe key’s organization is on a free plan. Nothing in the request ran.Upgrade the plan.
400, errors[].extensions.code = QUERY_TOO_DEEP or QUERY_TOO_COSTLYThe document asks for too much in one operation.Split it into smaller queries.
429Too many requests.Back off and retry.

The queries on this page fit well inside every limit.