api_access_token or the dashboard session credentials, with account membership. Supplying both credential families returns HTTP 400 with exactly {"error":{"code":"multiple_credentials"}}. Anonymous requests and account access denials return HTTP 401; authentication can use an errors array while access denials use an error string. The reference describes current behavior; proposed API scopes and MCP exposure are not authorization certification.
Readiness requires report access (ReportPolicy#view?; administrator in the open-code policy). Labeling health also requires administrator membership because it includes individual correction activity. Usage aggregates permits account administrators and managers and returns HTTP 403 to other user members. Agent-bot credentials are not supported by these reads. Deployment extensions can affect report access; this slice does not certify extension policy.
Readiness states are checked in this order:
since and until are whole Unix seconds, defaulting to the last 30 days. The start must precede the end and the interval cannot exceed 366 days. An explicit until includes its whole final second. Counts include conversations in the account’s configured Topics inboxes, with a current non-superseded rank 1 topic determining whether a conversation is labeled. remaining is max(50 - labeled, 0) in every state. Coverage is a fraction from 0 to 1 rounded to four decimals, or null with no conversations.
Disabled Topics returns HTTP 200 readiness with state: not_on and actual counts. Labeling health has no enablement gate: disabled or missing settings still returns HTTP 200 with actual statistics. Usage aggregates is independent of Topics enablement.
Labeling health accepts weeks (1–26, default 12) and backlog_days (1–365, default 90). Invalid bounds return HTTP 422. Coverage weeks are UTC calendar weeks using the account’s configured starting weekday, Monday by default.
lowVolume warns below 30 conversations, and lowLabels warns below 50 labels. The API still returns its counts and fractions. Empty datasets return zero counts, null fractions and timestamps, empty agent/team arrays, and populated zero-valued weekly buckets. A departed person’s name can be null. Agent and team names in published examples are synthetic Demo names.
Usage aggregates lives at GET /api/v1/analytics/usage-aggregates. Although its path lacks an account ID, account_id is required in the query. EnsureCurrentAccountHelper resolves that account after verifying membership and sets Current.account; the controller then requires administrator or manager membership. This is not session-only account selection. A signed-in user supplying a foreign, nonexistent or omitted account ID receives the same HTTP 401 account-access denial. Membership in multiple accounts allows reading the explicitly supplied account. P2 owns the broader account-resolution review.
period_start is inclusive and period_end exclusive ISO 8601 time, at most 366 days apart. The default metric is resolutions grouped by resolution_class,resolver,outcome; usage defaults to period_bucket,channel_type,billing_unit. See the operation for permitted dimensions, usage-only channel filtering and pagination. Quantities are fixed eight-place decimal strings: usage uses the selected billing unit and resolutions counts events. Empty groups return data: [] and has_more: false.
A persisted UTC calendar-month snapshot is returned when present, with frozen: true and snapshot version metadata. Otherwise the result is live with frozen: false and snapshot: null. An explicit positive version requires exactly a calendar month; missing versions return HTTP 404. Invalid inputs return HTTP 422. Live analytics unavailability or malformed responses return HTTP 503 with Usage aggregates are temporarily unavailable.
The examples are captured from real Rails integration requests against synthetic persisted conversations, corrections and billing outbox rows. Usage evidence exercises the persisted snapshot path with the existing ClickHouse boundary pattern: a verifying client double refuses any live execute call. It demonstrates account resolution, snapshot lookup, aggregation and rendering, and does not validate a live warehouse. The internal evidence records full response Content-Type and provenance, with IDs replaced by stable demo IDs and credentials omitted. Enterprise source is excluded from this documentation slice.