Skip to main content
The v2 report endpoints share one request and response shape: Visibility, Citations, Sentiment, Query Fanouts, Answers, and FactCheck (accuracy scores + claims). Learn it once and every report works the same way.
FactCheck uses the same { info, data } envelope but is per-category (no scope/assets/metrics params) and takes a narrower filter — a top-level and of single-field leaves, only topic negatable. See its pages for specifics.
All v2 endpoints accept names or UUIDs anywhere a filter takes a value. Get UUIDs from GET /v1/org/models, /v1/org/regions, /v1/org/personas, /v1/org/assets, /v1/org/categories, and the per-category …/topics, …/tags, …/prompts endpoints.

​
Common request fields

Unlike the v1 reports (where end_date is exclusive), v2 end_date is inclusive. To get June 9–15, send start_date: "2026-06-09", end_date: "2026-06-15".

​
Grouping

group_by turns one aggregate row into one row per value. Each grouped field is echoed back on the row:
  • Group by date (with interval) for a time series.
  • Rows carry a rank when grouped by a non-date dimension.
  • Available dimensions differ per report; see each endpoint’s reference.

​
Metrics

Request the metrics you want; they come back as named fields on each row (no positional arrays, no info.query lookup):

​
Scope and asset selection

  • scope: owned limits to assets/domains you own; all ranks across everything.
  • Visibility only: pick the asset(s) with the separate assets param: a name (is), a list (in, which overrides scope), or { op, value }. A selection returns all matches and ignores limit.
  • Sentiment requires an asset (sentiment is per-brand).

​
Filters

filter is a recursive tree, max depth 3, supported by all five reports:
Node types: { "and": [ … ] }, { "or": [ … ] }, { "not": <node> }, and leaves { "field", "op", "value" }.

​
Operators

value is a single value, or a list for in / not_in. Names or UUIDs; contains / matches match on names.

​
Two filter layers

Fields fall into two layers. They combine with and; or/not can’t mix layers (doing so returns 422). Prompt layer (full tree, full operator set): model, topic, region, persona, prompt, tag. Entity / citation layer (top-level and leaves only, varies per report):
For citations, filter domain in the domains report and page when you group_by: ["page"]; each filters its own report’s entity.

​
Sorting

Where supported, sort is { "field": "<metric>", "dir": "asc" | "desc" }. The field must be a requested, sortable metric (or date when grouped by date). Citations has no sort: it’s always ranked most-cited first.

​
Pagination

Responses return limit rows plus info.next_cursor. Pass that token back as cursor to get the next page; next_cursor is null on the last page.

​
Streaming

Every endpoint has a /stream variant (Server-Sent Events): a summary event (the info block), then one result event per row. limit/cursor are ignored; it returns everything by default. Pass max_results to cap.

​
Response shape

Every report returns { info, data }:
info echoes the resolved query (models in scope, the applied filter, dates, pagination); data is the rows, with metrics as named fields and any group_by dimensions attached.