> ## 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. # Get usage for a period > Usage broken into sections, with each row carrying the previous period's figure beside it so a comparison needs one call. Every row's `key` is what the drilldown endpoint takes as `row_key`. Check `freshness.state` and `load_state` before showing the numbers as final: `degraded` means part of the answer came from a fallback source. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/accounts/{account_id}/billing/usage 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. paths: /api/v1/accounts/{account_id}/billing/usage: parameters: - $ref: '#/components/parameters/account_id' get: tags: - Billing summary: Get usage for a period description: >- Usage broken into sections, with each row carrying the previous period's figure beside it so a comparison needs one call. Every row's `key` is what the drilldown endpoint takes as `row_key`. Check `freshness.state` and `load_state` before showing the numbers as final: `degraded` means part of the answer came from a fallback source. operationId: get-billing-usage parameters: - $ref: '#/components/parameters/billing_period' - $ref: '#/components/parameters/billing_from' - $ref: '#/components/parameters/billing_to' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/billing_usage' example: schema_version: '1' account_id: 1 period: month range_type: named custom_from: null custom_to: null period_start: '2026-09-01T00:00:00Z' period_end: '2026-10-01T00:00:00Z' timezone: UTC previous_period_start: '2026-08-02T00:00:00Z' previous_period_end: '2026-09-01T00:00:00Z' load_state: degraded freshness: source: clickhouse as_of: '2026-09-21T04:24:40Z' state: error last_ingested_event_at: null lag_seconds: null reconciliation: status: unknown outbox_totals: resolutions: count: 0 credits: '0.0' dollars: '0.0' channel_fees: count: 0 credits: '0.0' dollars: '0.0' other_variable_usage: count: 0 credits: '0.0' dollars: '0.0' analytics_totals: null drift: reason: Billing::ClickhouseClient::ConfigurationError sections: resolutions: title: Resolutions state: empty rows: - key: knowledge label: Knowledge count: 0 credits: '0.0' dollars: '0.0' pricing_state: published previous_count: 1 previous_credits: '5.0' previous_dollars: '0.35' - key: read label: Read count: 0 credits: '0.0' dollars: '0.0' pricing_state: published previous_count: 0 previous_credits: '0.0' previous_dollars: '0.0' totals: count: 0 credits: '0.0' dollars: '0.0' llm_passthrough: credits: '0.0' dollars: '0.0' byok: false itemized: [] previous_credits: '0.0' previous_dollars: '0.0' previous_totals: count: 6 credits: '54.0' dollars: '5.55' channel_fees: title: Channel Fees state: empty rows: - key: amb label: Apple Messages billable_unit: message direction: outbound count: 0 billable_quantity: '0.0' mixtures: [] subtotals: [] credits: '0.0' dollars: '0.0' previous_count: 1 previous_credits: '1.0' previous_dollars: '0.1' - key: rcs label: RCS billable_unit: message direction: outbound count: 0 billable_quantity: '0.0' mixtures: [] subtotals: [] credits: '0.0' dollars: '0.0' previous_count: 2 previous_credits: '100.0' previous_dollars: '10.0' totals: count: 0 credits: '0.0' dollars: '0.0' previous_totals: count: 6 credits: '104.0' dollars: '10.4' other_variable_usage: title: Other Variable Usage state: empty rows: - key: ask_tied label: Ask Tied count: 0 credits: '0.0' dollars: '0.0' previous_count: 0 previous_credits: '0.0' previous_dollars: '0.0' totals: count: 0 credits: '0.0' dollars: '0.0' previous_totals: count: 0 credits: '0.0' dollars: '0.0' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/error_message' security: - userApiKey: [] components: parameters: account_id: in: path name: id schema: type: integer required: true description: The numeric ID of the account billing_period: name: period in: query required: false description: Named reporting window. Defaults to `month`. schema: type: string enum: - day - week - month - quarter - year - custom example: month billing_from: name: from in: query required: false description: Start of a custom window, ISO-8601. Required when `period=custom`. schema: type: string billing_to: name: to in: query required: false description: End of a custom window, ISO-8601. Required when `period=custom`. schema: type: string schemas: billing_usage: type: object description: >- Usage for a period, broken into sections, with the equivalent figures for the previous period alongside each row. properties: schema_version: type: string description: >- Version of this payload's shape. Branch on it rather than on field presence. account_id: type: integer description: The account. period: type: string description: The window requested. range_type: type: string description: '`named` for a preset window, `custom` for an explicit range.' period_start: type: string description: ISO-8601 start of the window. period_end: type: string description: ISO-8601 end of the window. previous_period_start: type: string description: Start of the comparison window. previous_period_end: type: string description: End of the comparison window. timezone: type: string description: Timezone the windows are expressed in. load_state: type: string description: >- `loaded`, `empty` or `degraded`. `degraded` means some of it came from a fallback source. freshness: $ref: '#/components/schemas/billing_freshness' reconciliation: type: object description: >- Whether the analytics totals agree with what has been written to the ledger. `status: "unknown"` means the check could not run. sections: type: object description: >- One entry per section — `resolutions`, `channel_fees`, and so on. Each has a title, a state and `rows`, and each row carries a `key` that the drilldown endpoint takes as `row_key`. 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 billing_freshness: type: object description: >- Where this answer came from and how current it is. Billing reads several systems, so every response says which one it used — treat `state` other than `fresh` as a reason to be careful with the numbers rather than a failure. properties: source: type: string description: >- Which system answered — `postgres`, `clickhouse`, `stripe`, `billing_provider`, `postgres_override`. as_of: type: string description: ISO-8601 time the data was read. state: type: string description: '`fresh`, `stale`, `degraded` or `error`.' last_ingested_event_at: type: string nullable: true description: For the analytics source, the newest event it has. lag_seconds: type: number nullable: true description: How far behind that source is. 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.