> ## 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. # Usage aggregates > Read-only account aggregates. The path has no account ID, but required query account_id is resolved by EnsureCurrentAccountHelper into Current.account after membership validation; this is not session-only resolution. Requires a User membership with administrator or manager role. Foreign, nonexistent and omitted account IDs return the same 401 access denial for a signed-in user. period_start is inclusive and period_end exclusive, at most 366 days apart. Defaults to resolutions grouped by resolution_class,resolver,outcome; usage defaults to period_bucket,channel_type,billing_unit. Grouping dimensions must be unique. Usage supports period_bucket,channel_type,billing_unit,provider,carrier,direction,country; resolutions supports resolution_class,resolver,outcome. channel is usage-only. A persisted UTC calendar-month snapshot is used when available (latest by default); version requires exactly a calendar month and an existing version. Otherwise queries live analytics. Empty groups return data [] with has_more false. Topics enablement does not gate this endpoint. Provider unavailability or malformed analytics data returns 503. P2 owns the broader account-resolution review. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/analytics/usage-aggregates openapi: 3.0.4 info: title: Tied API description: >- The Tied REST API. Three families of endpoint, each with its own credential: **Application** for everything inside an account, **Platform** for provisioning accounts and users, and **Client** for acting as a contact from your own surface. version: 1.1.0 termsOfService: https://tied.com/legal contact: email: hello@tied.com license: name: MIT License url: https://opensource.org/licenses/MIT servers: - url: https://app.tied.com description: Tied cloud security: [] tags: - name: Account AgentBots description: Account-specific Agent Bots - name: Agents description: Agent management APIs - name: Canned Responses description: Pre-defined responses for common queries - name: Contacts description: Contact management APIs - name: Contact Labels description: Manage contact labels - name: Conversation Assignments description: Manage conversation assignments - name: Conversation Labels description: Manage conversation labels - name: Conversations description: Conversation management APIs - name: Custom Attributes description: Custom fields for contacts and conversations - name: Custom Filters description: Saved filters for conversations - name: Inboxes description: Communication channels setup - name: Integrations description: Third-party integrations - name: Messages description: Message management APIs - name: Profile description: User profile APIs - name: Reports description: Analytics and reporting APIs - name: Teams description: Team management APIs - name: Webhooks description: Event notification webhooks - name: Automation Rule description: Workflow automation rules - name: Help Center description: Knowledge base management - name: Contacts API description: Public contact APIs - name: Conversations API description: Public conversation APIs - name: Messages API description: Public message APIs - name: CSAT Survey Page description: Customer satisfaction survey - name: Account description: >- The authenticated user's own account — read and update account settings. Distinct from the Platform family's **Accounts**, which provisions accounts across an installation. - name: Audit Logs description: Read the account's audit trail - name: Inbox API description: Public inbox lookup by channel identifier - name: Labels description: >- Create and manage the account's labels. Applying one to a conversation or contact is a separate endpoint under those resources. - name: Macros description: >- Saved multi-step actions an agent — or an integration — can run against one or more conversations. - name: Campaigns description: Ongoing website campaigns and one-off SMS and WhatsApp sends. - name: Contact Notes description: Internal notes on a contact. Never visible to the contact. - name: Help Center Categories description: Categories group a portal's articles, one tree per allowed locale. - name: Help Center Articles description: The articles a portal publishes, and their draft and archived states. - name: Summary Reports description: Per-agent, per-team, per-inbox and per-label totals for a period, as JSON. - name: Live Reports description: Right-now queue counts. No date range — these describe the present. - name: CSAT description: >- The satisfaction ratings contacts have submitted, and the metrics computed from them. - name: Notifications description: >- The per-user notification feed, its read and snooze state, and the settings that decide what lands in it. - name: Conversation Participants description: >- The agents watching a conversation. Participants get notified about it without being assigned to it. - name: Draft Messages description: >- The unsent reply held for a conversation. Stored in Redis, one per conversation. - name: Search description: >- One search service across conversations, contacts, messages and Help Center articles. - name: Dashboard Apps description: Embedded pages that appear as a tab beside a conversation. - name: Assignment Policies description: How conversations are handed out, and which inbox uses which policy. - name: Files description: Storing a file so another endpoint can attach it. - name: Bot Flows description: >- Scripted conversation flows, their versions, and the publish and rollback that move between them. - name: Billing description: >- Credit balance, usage, invoices, spend controls and the provider-hosted payment flows. - name: AMB Templates description: >- Saved Apple Messages primitive payloads an agent can reuse from the composer. - name: AMB Onboarding description: The in-flight Apple Messages for Business registration for an account. - name: Widget Session description: Starting a widget session and reading the visitor it belongs to. - name: Widget Conversation description: The visitor's conversation and its messages. - name: Widget Context description: Campaigns, agents, labels, events and uploads for a widget session. - name: CSAT Survey description: The public, unauthenticated survey a contact answers from a link. - name: Workspace description: Scheduling and cancelling deletion of the whole workspace. - name: Widget Integrations description: Provider actions available to a visitor session in its own conversation. - name: Orchestration Studio description: >- Administrator-only read APIs for Orchestration Studio cases and knowledge sources. - name: Topic Analytics description: Account Topics readiness, labeling health and usage aggregates. - name: Analytics V2 description: >- Account-scoped metrics, anonymized benchmarks and audited conversation drilldown. paths: /api/v1/analytics/usage-aggregates: get: tags: - Topic Analytics summary: Usage aggregates description: >- Read-only account aggregates. The path has no account ID, but required query account_id is resolved by EnsureCurrentAccountHelper into Current.account after membership validation; this is not session-only resolution. Requires a User membership with administrator or manager role. Foreign, nonexistent and omitted account IDs return the same 401 access denial for a signed-in user. period_start is inclusive and period_end exclusive, at most 366 days apart. Defaults to resolutions grouped by resolution_class,resolver,outcome; usage defaults to period_bucket,channel_type,billing_unit. Grouping dimensions must be unique. Usage supports period_bucket,channel_type,billing_unit,provider,carrier,direction,country; resolutions supports resolution_class,resolver,outcome. channel is usage-only. A persisted UTC calendar-month snapshot is used when available (latest by default); version requires exactly a calendar month and an existing version. Otherwise queries live analytics. Empty groups return data [] with has_more false. Topics enablement does not gate this endpoint. Provider unavailability or malformed analytics data returns 503. P2 owns the broader account-resolution review. operationId: get-usage-aggregates parameters: - name: account_id in: query description: Account to resolve through the authenticated caller membership. schema: type: integer required: true - name: period_start in: query description: Inclusive ISO 8601 start. schema: type: string format: date-time required: true - name: period_end in: query description: Exclusive ISO 8601 end; maximum interval 366 days. schema: type: string format: date-time required: true - name: metric in: query description: Aggregate measure. schema: type: string enum: - usage - resolutions default: resolutions - name: group_by in: query description: Comma-separated dimension names; must be unique. schema: type: string - name: channel in: query description: Optional usage channel filter from the supported channel types. schema: type: string - name: version in: query description: Positive persisted snapshot version. schema: type: integer minimum: 1 - name: page in: query description: One-based page. schema: type: integer minimum: 1 default: 1 - name: per_page in: query description: Rows per page. schema: type: integer minimum: 1 maximum: 100 default: 50 responses: '200': description: Actual synthetic request response; see topic analytics evidence. content: application/json: schema: $ref: '#/components/schemas/topic_usage_aggregates' example: schema_version: '1' account_id: 1 period_start: '2026-08-01T00:00:00Z' period_end: '2026-09-01T00:00:00Z' metric: resolutions group_by: - resolution_class - resolver - outcome data: - dimensions: resolution_class: read resolver: orch_agent outcome: confirmed quantity: '1.00000000' pagination: page: 1 per_page: 50 has_more: false frozen: true snapshot: version: 1 latest_version: 1 closed_at: '2026-10-07T12:00:00Z' reason: period_close supersedes_version: null x-example-provenance: source: spec/contract/topic_analytics_spec.rb capture: >- Actual synthetic Rails integration response; full Content-Type and scrub details in docs/platform-api/topic-analytics-evidence/responses.json. scrubbed: true '400': description: >- The request presented both a Devise Token Auth session credential and an api_access_token. The request is refused before the action runs. content: application/json: schema: type: object required: - error properties: error: type: object required: - code properties: code: type: string enum: - multiple_credentials additionalProperties: false additionalProperties: false example: error: code: multiple_credentials '401': description: >- Unauthenticated or account is not accessible to the caller. Devise authentication responses may use an `errors` array; account access denials use `error`. content: application/json: schema: oneOf: - $ref: '#/components/schemas/error_message' - type: object required: - errors properties: errors: type: array items: type: string '403': description: Member is neither an administrator nor a manager. content: application/json: schema: $ref: '#/components/schemas/error_message' '404': description: Requested snapshot version does not exist. content: application/json: schema: $ref: '#/components/schemas/error_message' '422': description: Invalid period, window, grouping, metric, pagination or version. content: application/json: schema: $ref: '#/components/schemas/error_message' '503': description: Usage aggregates are temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/error_message' security: - userApiKey: [] components: schemas: topic_usage_aggregates: type: object description: Versioned account-scoped usage or resolution aggregates. required: - schema_version - account_id - period_start - period_end - metric - group_by - data - pagination - frozen - snapshot properties: schema_version: type: string description: Aggregate schema version. enum: - '1' account_id: type: integer description: >- Account resolved from the required account_id query parameter after membership checks. period_start: type: string description: Inclusive period start. format: date-time period_end: type: string description: Exclusive period end. format: date-time metric: type: string description: Measure being aggregated. enum: - usage - resolutions group_by: type: array description: Effective grouping dimension names. items: type: string description: Grouping dimension. data: type: array description: One page of groups; empty data means no groups. items: type: object description: One aggregate group. required: - dimensions - quantity properties: dimensions: type: object description: Requested dimensions only; values are strings or null. additionalProperties: type: string nullable: true quantity: type: string description: >- Fixed eight-place decimal string. Usage uses billing_unit; resolutions counts events. pattern: ^-?\d+\.\d{8}$ pagination: type: object description: Pagination. required: - page - per_page - has_more properties: page: type: integer description: One-based page. minimum: 1 per_page: type: integer description: Maximum rows per page. minimum: 1 maximum: 100 has_more: type: boolean description: Whether another page exists. frozen: type: boolean description: True when served from an account-scoped persisted monthly snapshot. snapshot: type: object description: Snapshot metadata, or null for live periods. required: - version - latest_version - closed_at - reason - supersedes_version properties: version: type: integer description: Returned snapshot version. minimum: 1 latest_version: type: integer description: Latest version for this account and month. minimum: 1 closed_at: type: string description: Snapshot close timestamp. format: date-time reason: type: string description: Reason for snapshot creation. enum: - period_close - late_event supersedes_version: type: integer description: Previous version for a correction, else null. nullable: true minimum: 1 nullable: true error_message: type: object description: >- The shape returned by `render_unauthorized`, `render_not_found_error` and `render_could_not_create_error`. properties: error: type: string description: A single human-readable message. example: Resource could not be found required: - error securitySchemes: userApiKey: type: apiKey in: header name: api_access_token description: >- This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.