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”.
The endpoint
Section titled “The endpoint”POST https://api.beket.ai/graphqlNote 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.
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.
Which section to read
Section titled “Which section to read”| You want | Query | Audit mode |
|---|---|---|
| Headline metrics, summary, key findings | reportOverview | brand |
| Unprompted recall and the per-engine visibility gap | reportVisibilityMetrics | brand |
| The prompts you could win, paged | reportWinnableQueries | brand |
| The content roadmap and off-site opportunities | reportRoadmap | brand |
| The market leaderboard | marketReport | market |
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.
Report summary
Section titled “Report summary”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 } } }}Winnable prompts
Section titled “Winnable prompts”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.
Content roadmap
Section titled “Content roadmap”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 } }}Market leaderboard
Section titled “Market leaderboard”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 } } }}When it refuses
Section titled “When it refuses”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.
| Response | Meaning | What to do |
|---|---|---|
data.<section> is null, no errors | No 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 = UNAUTHENTICATED | The key is missing, revoked or expired. | Check the key. |
200, errors[].extensions.code = UNAUTHORIZED | The audit belongs to another organization, or does not exist. | Check the id and which organization the key belongs to. |
402, errors[].extensions.code = PAYMENT_REQUIRED | The 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_COSTLY | The document asks for too much in one operation. | Split it into smaller queries. |
429 | Too many requests. | Back off and retry. |
The queries on this page fit well inside every limit.
- Quickstart — the whole loop, ending here
- Results reference — snapshots, comparisons and the raw answer export