Concepts
Behavior that spans multiple endpoints, not tied to one operation's field list.
The API Reference documents every field on every endpoint. This page covers the handful of things that only make sense once you see them across endpoints.
Date-range windows
The two analytics endpoints (GET /api/brands/{brandId}/analytics/ and GET /api/categories/{categoryId}/analytics/) and the score-history endpoints all accept the same window parameters:
| Param | Values | Notes |
|---|---|---|
range | 7d, 30d, 90d, all | a rolling preset |
range=custom + start + end | start=YYYY-MM-DD&end=YYYY-MM-DD | an explicit range |
With no date params, the window defaults to 30d. A bad range, a malformed or out-of-order custom range, or an end in the future returns 400 with field errors.
Every figure in an analytics response is computed the same way the dashboard computes it, so a report built from the API and the dashboard agree over the same window.
Own-org only. A brand or category in another org returns 404, never 403 or 200, so a token can't tell whether a resource exists in someone else's org.
Suppressed deltas
Any field named delta, shareDelta, or similar is paired with a suppressedReason field. When there is nothing meaningful to compare against, the delta is null with a reason (no_data, no_boundary, no_prior, or cross_era) rather than being fabricated as 0. Render a dash or the reason, not a zero, when suppressedReason is set.
Runs and responses: light list, heavy drill-down
GET /api/runs/{runId}/ returns a run's responses[] as a light list: the extracted facts (mentioned, sentiment, rank, sources) plus hasText and textLength, but not the answer text itself. To read the full answer, take a response row's id and fetch GET /api/responses/{id}/, which adds answerText (and, with ?includeHtml=true, answerHtml).
Use hasText and textLength on the light rows to decide which responses are worth the extra request before fetching them one at a time.
Recommendations ordering and access
GET /api/brands/{brandId}/recommendations/ returns the same set the dashboard shows: superseded and soft-deleted rows are excluded, and every open recommendation is included, not just the ones a user has already acted on. Order is priority bucket (high, then medium, then low), then score descending, then newest first.
Recommendations require a Pro or higher plan (they are a Knowledge Graph feature). An organization that is not on an eligible plan gets 403, the same signal the dashboard returns, rather than an empty list, so a client can tell "not on your plan" apart from "this brand has no recommendations."