/v1/brands/{brand_id}/citations/series Citations over time
Citations per day or week, one point per bucket and key, with every answer in the bucket so a share can be drawn. group picks the key: site_type (default; classifying while a site is not classified yet), relation, page_category, domain or url; domain and url need the keys to chart in key (repeat, up to 50). An answer with no engine recorded counts in neither its citations nor its answers, as in the answers per day and engine.
Filters compose with AND: report_id (repeat for several), scheduled_report_id, platform (repeat for several engines), date_from, date_to and category (the prompt category; repeat for several). bucket is day (default) or week, counted in tz (an IANA zone, default UTC; a week starts on Monday). Returns every point, oldest first.
Path parameters
-
Brand UUID.
Query parameters
-
What each line counts.
one of site_type, relation, domain, page_category, url · default: site_type
-
Only these site types, relations, categories, domains or URLs; repeat for several.
-
day(default) orweek.one of day, week · default: day
-
IANA time zone the days and weeks are counted in, e.g.
America/New_York. DefaultUTC.default: UTC
-
Only these reports (UUIDs); repeat the parameter for several.
-
allfor every completed report of the brand, in place of naming each one; the other filters still apply. -
Only the runs of this Scheduled Report (UUID).
-
Only the runs of these trackers (a report's
tracker_id; a scheduled report's id is its tracker's); repeat the parameter for several. -
Only the runs in these markets (a report's
market_id, a region config'sid); repeat the parameter for several. -
Only the runs in these places, as
country|citylowercased (united states|austin, orunited states|for the whole country;country|city|regionfor a town keyed apart from its namesake,australia|emerald|victoria), across every tracker; repeat the parameter for several. -
defaultreads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter;allreads every completed report of the brand. -
Only answers from these engines; repeat the parameter for several.
-
Only answers from this moment on (ISO-8601).
-
Only answers before this moment, exclusive (ISO-8601); not before
date_from. -
Only answers to prompts of these categories; repeat the parameter for several.
-
Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns
200with adry_runobject reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns422.default: false
Responses
Example response
{
"data": [
{
"answers": 64,
"avg_position": 3.2,
"bucket": "2026-09-20T00:00:00+00:00",
"citation_count": 17,
"cited_answers": 12,
"key": "news",
"object": "citation_series_point"
}
],
"object": "list"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "validation_error",
"message": "Request validation failed"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "unauthorized",
"message": "Missing or invalid credentials"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "forbidden",
"message": "You do not have permission to access this resource"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "not_found",
"message": "Resource not found"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "conflict",
"message": "Resource conflict"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "rate_limit_exceeded",
"message": "Per-minute rate limit exceeded"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "service_unavailable",
"message": "Service temporarily unavailable, please retry"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}