Errors

Errors returned by the analytics endpoints use one stable envelope:

{
  "error": {
    "code": "unknown_member",
    "message": "Unknown analytics member.",
    "param": "not_a_member",
    "request_id": "request-id-from-x-request-id"
  }
}

param is included when a specific request field or member caused the error. Every matched analytics endpoint response includes x-request-id; on errors it matches error.request_id. Unknown paths and unsupported methods return Fastify’s default JSON 404 without this envelope, x-request-id, or an Allow header. The service does not currently return 405 Method Not Allowed.

HTTP status	Code	Meaning
401	`unauthorized`	The bearer key is missing, malformed, unknown, or revoked.
403	`insufficient_scope`	The key is valid but does not include `analytics:read`.
429	`rate_limited`	A rate or admission limit was exceeded. Read `Retry-After`.
400	`invalid_query`	The JSON body or query grammar is invalid.
400	`unknown_member`	A model, metric, dimension, or filter member is not in the catalog.
400	`range_too_large`	The inclusive date range exceeds 366 days.
400	`invalid_cursor`	The signed cursor is malformed, tampered with, or does not match the query.
500	`internal_error`	An unexpected application or infrastructure failure occurred.

The published model names are agent_runs and agent_user_activity; any other model name returns unknown_member. A well-formed key that is unknown or revoked normally returns 401. While the global credential-verification limit described in Authentication is exhausted, the same request returns 429 with Retry-After instead. A missing or malformed credential always returns 401. Ordering has two grammar rules, and both violations return invalid_query. Order terms must reference selected members, so ordering by a member that is not in metrics or dimensions returns invalid_query even when the member is not in the catalog at all. Order also requires at least one dimension: a totals query rejects any order. A request with a missing or unsupported Content-Type, or with a body larger than 1 MiB, is also rejected as 400 invalid_query. Body parsing happens before bearer authentication and the custom rate limits. A malformed query body can therefore return 400 before the same request would otherwise return 401 or 429. Messages for the four query-domain codes are safe for callers. Statement timeouts and infrastructure failures remain internal_error; they are not converted into query errors.

Getting Started

API Guides

Analytics