> ## Documentation Index > Fetch the complete documentation index at: https://docs.together.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get billing usage > Returns an organization's billing usage for a month as cost-annotated line items grouped into time windows. Finalized windows are returned through the end of yesterday at daily granularity, or the last completed hour at hourly granularity (UTC). This endpoint is in beta and is enabled per organization. [Contact support](https://portal.usepylon.com/together-ai/forms/support-request) to request access or share feedback. Calls from an organization without access return a 404. The response shape can change while the endpoint is in beta. `organization_id` is optional in beta but will be required at GA, so send it now to avoid a breaking change. This endpoint returns usage for the API key's entire organization, not only the key's project. Any project's key can read it, including keys created by [external collaborators](/docs/roles-permissions#external-collaborators-beta), and access can't be restricted to organization admins. When project-scoped keys start enforcing their scope, you will need to swap the key you use here for one with organization-level access. Usage data for the current month can be up to 1 hour behind. Data for prior months can be up to 24 hours behind. When reading line items: * `product_name` values are display names, not stable identifiers, and can change without notice. * `attributes` vary by product. For example, `api_key_id` and `project_id` are only set on inference line items. ## OpenAPI ````yaml openapi.yaml GET /billing/usage openapi: 3.1.0 info: title: Together APIs description: The Together REST API. See https://docs.together.ai for more details. version: 2.0.0 termsOfService: https://www.together.ai/terms-of-service contact: name: Together Support url: https://www.together.ai/contact license: name: MIT url: https://github.com/togethercomputer/openapi/blob/main/LICENSE servers: - url: https://api.together.ai/v1 description: Default environment for APIs - url: https://api-inference.together.ai/v2 description: Optimized environment for inference security: - bearerAuth: [] paths: /billing/usage: get: tags: - Billing summary: Get billing usage description: > Returns an organization's billing usage for a month as cost-annotated line items grouped into time windows. Finalized windows are returned through the end of yesterday at daily granularity, or the last completed hour at hourly granularity (UTC). operationId: getBillingUsage parameters: - name: month in: query schema: description: >- Billing month in YYYY-MM format. Defaults to the current month, which returns data through yesterday (daily) or the last completed hour (hourly). type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ - name: organization_id in: query schema: description: >- Organization to report on. Usage is always reported for the organization that owns the API key, so this is optional; supplying an ID that is not that organization returns 403. type: string minLength: 1 - name: granularity in: query schema: description: >- Time window size for rows. 'hour' returns ~24x more rows than 'day'. type: string enum: - day - hour default: day - name: limit in: query schema: description: Maximum number of time windows per page (max 1000). type: integer minimum: 1 maximum: 1000 default: 100 - name: after in: query schema: description: >- Opaque cursor from a previous response's `next_cursor`. Only valid for the month and granularity it was issued for. Current-month data is a moving snapshot: each page reflects data as of its request, so newly completed windows may appear at the end of the sequence. type: string responses: '200': description: Billing usage report for the requested month content: application/json: schema: $ref: '#/components/schemas/BillingUsageReport' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorData' '401': description: Unauthorized — missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorData' '403': description: >- Forbidden — organization_id does not match the organization that owns the API key content: application/json: schema: $ref: '#/components/schemas/ErrorData' '404': description: Not found — the endpoint is not enabled for this organization content: application/json: schema: $ref: '#/components/schemas/ErrorData' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorData' x-codeSamples: - lang: Shell label: cURL source: > # First page curl "https://api.together.ai/v1/billing/usage?month=2026-06&granularity=day" \ -H "Authorization: Bearer $TOGETHER_API_KEY" # Next page: pass the previous response's next_cursor curl "https://api.together.ai/v1/billing/usage?month=2026-06&granularity=day&after=NEXT_CURSOR" \ -H "Authorization: Bearer $TOGETHER_API_KEY" components: schemas: BillingUsageReport: type: object required: - object - organization_id - billing_period - earliest_window_start - latest_window_end - currency - data - next_cursor properties: object: type: string const: list organization_id: type: string description: ID of the organization the report belongs to. billing_period: type: string description: Billing month (YYYY-MM). earliest_window_start: type: string format: date-time nullable: true description: >- Start of the earliest time window with usage in the month (UTC, ISO 8601); null when the month has no usage. latest_window_end: type: string format: date-time nullable: true description: >- Exclusive end of the latest time window with usage in the month (UTC, ISO 8601); null when the month has no usage. Describes the whole month, not the current page. currency: type: string const: USD data: type: array description: Time windows containing usage line items. items: $ref: '#/components/schemas/BillingUsageWindow' next_cursor: type: string nullable: true description: Opaque cursor for the next page; null when this is the last page. ErrorData: type: object required: - error properties: error: type: object properties: message: type: string nullable: false type: type: string nullable: false param: type: string nullable: true default: null code: type: string nullable: true default: null required: - type - message BillingUsageWindow: type: object required: - date - start_time - end_time - line_items properties: date: type: string description: >- Day this window covers (UTC, YYYY-MM-DD). Present for both granularities. start_time: type: string format: date-time description: >- Window start (UTC, ISO 8601). Start of the day (daily) or hour (hourly). end_time: type: string format: date-time description: >- Window end (UTC, ISO 8601), exclusive. Start of the next day (daily) or hour (hourly). line_items: type: array description: Usage line items in this time window. items: $ref: '#/components/schemas/BillingUsageLineItem' BillingUsageLineItem: type: object required: - product_name - quantity - unit_price - cost - pricing_dimensions - attributes properties: product_name: type: string description: Metronome product name (e.g. 'Serverless Inference - Input Tokens'). quantity: type: string description: >- Total usage for the window in the product's native unit (GPU-hours, tokens, ...) as a decimal string. unit_price: type: string description: Per-unit price in USD as a decimal string. cost: type: string description: Total cost for this line item in USD as a decimal string. pricing_dimensions: type: object description: >- Rate-determining dimensions (varies by product). Passthrough from Metronome pricing group values. additionalProperties: type: string attributes: type: object description: Resource identifiers for attribution, varying by product. additionalProperties: type: string securitySchemes: bearerAuth: type: http scheme: bearer x-bearer-format: bearer x-default: default ````