> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tied.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Topic analytics

> Account readiness, labeling health and usage aggregate contracts.

These eight reads cover Topics readiness, the complete labeling-health response, its five separate panels, and usage aggregates. Each panel has its own generated reference page in Reporting → Topic analytics.

Use a user `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:

| State | Condition |
| - | - |
| `not_on` | No Topics settings row, or Topics disabled |
| `low_volume` | Fewer than 30 conversations in the period |
| `learning` | Fewer than 50 labeled conversations |
| `partial` | At least 50 labeled, but labeled / conversations below 0.5 |
| `ok` | All other enabled periods |

`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.

| Panel | Units and meaning |
| - | - |
| `coverage` | Weekly and total conversation counts and labeled fractions; includes empty weeks |
| `backlog` | Unlabeled conversation counts aged 0–1, 2–7, 8–30 and over 30 whole days, bounded by `backlog_days`; oldest timestamp is UTC or null |
| `agents` | Human set and clear correction events in the weekly window; repeated corrections count separately; at most 100 people, ordered by sets descending then user ID |
| `teams` | Conversation counts and labeled fractions for the current team; top 100 teams, then no-team and optional `otherTeams` overflow row; rows add to the window total |
| `sources` | Current main-topic counts and fractions for `person`, `rule`, `ai`; fractions divide by the labeled count |

`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.