Core concepts
Seven nouns carry this API. Understanding how they nest is most of what you need to use it well.
Audit one measurement target + its configuration ├─ Profile the brand details prompts are generated from ├─ Connectors which AI surfaces get asked ├─ Prompts the questions asked └─ Run one execution of those prompts └─ Snapshot the result, frozen in time └─ Report the readable rendering of a snapshotOne measurement target plus its configuration. The target is a brand’s domain — a brand
audit, measuring how often AI surfaces name that brand — or a topic, for a market audit that
ranks whoever they name. The mode field on each audit says which.
Creating an audit does not begin measuring — it is created PENDING, and in that state it can do
nothing else yet. Besides a domain or a topic, you can name the target with an inline profile
when you already know the brand details.
The required next call is POST /audits/{auditId}/prepare, which explores the target and infers
the profile the prompts are generated from. See the status lifecycle.
The status lifecycle
Section titled “The status lifecycle”An audit’s status is not decoration — several endpoints gate on it, and a call made in the wrong
state answers 409 rather than queueing.
PENDING just created; no profile yet │ POST /audits/:id/prepare (async, answers 202) ▼ PREPARING exploring, inferring the profile, selecting angles │ ▼ AWAITING_CONFIG ← the state everything else requires AWAITING_PROMPTS (same, after prompts have been generated) │ POST /audits/:id/start (async, answers 202) ▼ CRAWLING → EXPLORING → … → COLLECTING → PROCESSING │ ▼ COMPLETED / FAILED| You want to call | Required status | Otherwise |
|---|---|---|
POST /audits/:id/prompts/generate | AWAITING_CONFIG or AWAITING_PROMPTS | 409 |
POST /audits/:id/start | AWAITING_CONFIG or AWAITING_PROMPTS | 409 |
PATCH on profile / connectors | Not mid-run — the two above, or COMPLETED / FAILED | 409 |
The consequence worth internalising: a newly created audit cannot do anything yet. It is
PENDING, it has no profile, and prompts are generated from that profile. POST /audits/:id/prepare
is what moves it forward, and because that work runs on a queue, you must poll
GET /audits/:id until the status changes rather than calling the next endpoint straight away.
Profile
Section titled “Profile”The brand details prompts are generated from. Extracted automatically when possible, editable by you.
PATCH /audits/{auditId}/profile replaces rather than patches: send the whole object, because
absent nullable fields are written as null. Reading it before an extraction has happened returns an
empty profile object rather than a 404, so a client can render its form either way.
Connectors
Section titled “Connectors”Which AI surfaces this audit queries. The available set and the maximum count are both plan-dependent.
The behaviour that surprises people: a selection is clamped to the plan’s ceiling rather than
rejected. Read maxConnectors and effectiveConnectors back from the response to see what was
actually kept. GET /audits/{auditId}/config-options tells you what is selectable before you try.
Prompts
Section titled “Prompts”The questions the audit asks. Generated from the profile, then reviewed and selected.
Generation costs money, so it is a one-time step per audit rather than something to retry casually.
The plan’s ceiling on how many prompts may be selected is maxQueries, and exceeding it is
rejected when the run starts, not when you select them.
One execution of the audit’s prompts against the selected surfaces. Asynchronous by nature — measuring is not instant.
Endpoints that start work answer 202 with a status to poll. GET /audits/{auditId}/run returns
retryAfterMs, which varies with the phase the run is in; use it rather than a fixed interval.
There are two entry points. POST /audits/{auditId}/start is the normal one: send the
configuration and the run is enqueued. POST /audits/{auditId}/run is lower-level — it resumes and
re-measures rather than re-asking the connectors for angles that already completed.
Snapshot
Section titled “Snapshot”The result of a run, frozen in time. This is the unit of history, and the cheapest thing to watch.
The snapshot list is newest-first and cursor-paginated, and each item carries summary metrics plus
reportAvailable — whether that snapshot can hydrate a report. Poll this, not the report.
To see what moved between two snapshots, GET /audits/{auditId}/snapshots/compare diffs them:
prompts, metrics, competitors, cited sources and the report’s recommendations.
Full and short snapshots
Section titled “Full and short snapshots”A short audit is a cost-optimized refresh, not a partial report: it runs only the sampled queries
and carries every un-run answer forward from the prior snapshot. Both kinds hydrate the same report.
Select on reportAvailable rather than on the snapshot’s type.
Report
Section titled “Report”The readable rendering of a snapshot — every section the dashboard shows.
The report is read through GraphQL, one section at a time, naming only the fields you want — see Reading the report. It changes only when a run completes, so read it when a new snapshot appears rather than on a timer.
Reading efficiently
Section titled “Reading efficiently”Response size is a real cost for both of us, and the endpoints are designed around that rather than apologising for it afterwards.
| You want | Use | Not |
|---|---|---|
| To notice a new result | GET /audits/:id/snapshots | The report, polled |
| What changed since last time | GET /audits/:id/snapshots/compare | Two reports, diffed client-side |
| One report section | POST /graphql, naming the fields | Every section, in case |
| Every answer, raw | GET /audits/:id/answers/export, paged by date | The report, unpicked |
| Organization-wide totals | GET /analytics/portfolio | Every audit, fetched and summed |
GET /analytics/portfolio is bounded by design: portfolio totals and at most ten competitors. It
will not grow to carry per-audit detail — use the single-audit endpoints for that.
- Quickstart — the whole loop, end to end
- Reading the report — every report section, in GraphQL
- API reference — every documented endpoint