> ## Documentation Index > Fetch the complete documentation index at: https://docs.aireserve.com/llms.txt > Use this file to discover all available pages before exploring further. # Usage and billable amounts per end customer > What each of your end customers used in the period, what it cost your organization (`cost_usd`), and — when your organization has pricing rules for its customers — what the customer owes (`billable_usd`) and your margin. Customers are the opaque ids you tagged requests with via `x-aireserve-customer` (or the OpenAI `user` field). Requests with no tag are reported once as `untagged`, cost only. Failed requests are never billed and are not counted in `requests`. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/customers/usage openapi: 3.0.3 info: title: AI Reserve Gateway API description: >- The AI Reserve API surface — OpenAI-compatible chat completions, Anthropic-compatible messages, Bedrock Converse, images, video, files, text-to-speech, realtime voice sessions, and provider-hidden GPU infrastructure — all behind one endpoint and one API key. version: 1.0.0 servers: - url: https://api.aireserve.com security: - bearerAuth: [] tags: - name: Customers description: >- Per-end-customer usage, cost, and billable amounts for organizations that tag requests with their own customers. - name: GPU Infrastructure description: >- Provision and manage provider-hidden GPU instances. The recommended Instances API accepts workload requirements and an hourly price ceiling; AI Reserve handles provider placement internally. Every mutation is asynchronous and returns an operation to poll. - name: Customer keys description: >- Mint, list, and revoke API keys pinned to your own end customers (and their organizations), so spend splits per customer without per-request tagging. paths: /v1/customers/usage: get: tags: - Customers summary: Usage and billable amounts per end customer description: >- What each of your end customers used in the period, what it cost your organization (`cost_usd`), and — when your organization has pricing rules for its customers — what the customer owes (`billable_usd`) and your margin. Customers are the opaque ids you tagged requests with via `x-aireserve-customer` (or the OpenAI `user` field). Requests with no tag are reported once as `untagged`, cost only. Failed requests are never billed and are not counted in `requests`. operationId: listCustomerUsage parameters: - name: start in: query required: false description: >- Inclusive start of the period: a UTC date (`2026-10-01`) or an RFC 3339 timestamp. Defaults to 30 days before `end`. schema: type: string - name: end in: query required: false description: >- Exclusive end of the period: a UTC date or an RFC 3339 timestamp. Defaults to now. The period may span at most 92 days. schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CustomersUsageReport' '400': description: >- Malformed `start`, `end`, `group_by`, or customer id; or a period longer than 92 days. content: application/json: schema: $ref: '#/components/schemas/CustomerUsageError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/CustomerUsageError' '403': description: >- The key is valid but a screen (IP allowlist, country, suspension) rejected the request. content: application/json: schema: $ref: '#/components/schemas/CustomerUsageError' '429': description: Per-organization rate limit exceeded. Honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/CustomerUsageError' security: - bearerAuth: [] components: schemas: CustomersUsageReport: type: object properties: period: type: object properties: start: type: string description: Inclusive start, RFC 3339 UTC. end: type: string description: Exclusive end, RFC 3339 UTC. required: - start - end additionalProperties: false description: The period the figures cover. currency: type: string enum: - USD has_pricing_rules: type: boolean description: >- Whether at least one of your pricing rules applies to the period. When false, billable_usd and margin fields are omitted everywhere. truncated: type: boolean description: >- True when the period held more rows than one response carries and the cheapest were dropped. Narrow the period or query one customer. customers: type: array items: type: object properties: customer_id: type: string description: Your opaque end-customer id, exactly as tagged on requests. requests: type: integer minimum: 0 maximum: 9007199254740991 description: >- Successful requests. Failed requests are never billed to a customer and are not counted. prompt_tokens: type: integer minimum: 0 maximum: 9007199254740991 description: Prompt tokens over successful requests. completion_tokens: type: integer minimum: 0 maximum: 9007199254740991 description: Completion tokens over successful requests. cost_usd: type: string pattern: ^-?\d+\.\d{6}$ description: >- What this usage cost your organization (your billed cost, six-decimal USD string). billable_usd: description: >- What the end customer owes under your price list. Present only when your organization has at least one pricing rule in the period. type: string pattern: ^-?\d+\.\d{6}$ margin_usd: description: >- billable_usd minus cost_usd. Present only when pricing rules exist. type: string pattern: ^-?\d+\.\d{6}$ margin_pct: description: >- margin_usd / billable_usd × 100 (gross margin), two decimals; null when billable_usd is zero. Present only when pricing rules exist. nullable: true type: number priced: type: boolean description: >- True when every request in this row matched a pricing rule. False when some usage was counted at cost (no matching rule). required: - customer_id - requests - prompt_tokens - completion_tokens - cost_usd - priced additionalProperties: false description: One row per tagged customer, highest cost first. untagged: type: object properties: requests: type: integer minimum: 0 maximum: 9007199254740991 description: >- Requests that carried no customer tag (all requests, including failed ones). total_tokens: type: integer minimum: 0 maximum: 9007199254740991 cost_usd: type: string pattern: ^-?\d+\.\d{6}$ description: USD amount as a six-decimal string. Never a float. required: - requests - total_tokens - cost_usd additionalProperties: false description: >- Usage with no x-aireserve-customer tag. Cost only — untagged requests are never priced. Sourced from hourly aggregates, so it can trail live traffic by a few minutes. totals: type: object properties: requests: type: integer minimum: 0 maximum: 9007199254740991 description: >- Successful requests. Failed requests are never billed to a customer and are not counted. prompt_tokens: type: integer minimum: 0 maximum: 9007199254740991 description: Prompt tokens over successful requests. completion_tokens: type: integer minimum: 0 maximum: 9007199254740991 description: Completion tokens over successful requests. cost_usd: type: string pattern: ^-?\d+\.\d{6}$ description: >- What this usage cost your organization (your billed cost, six-decimal USD string). billable_usd: description: >- What the end customer owes under your price list. Present only when your organization has at least one pricing rule in the period. type: string pattern: ^-?\d+\.\d{6}$ margin_usd: description: >- billable_usd minus cost_usd. Present only when pricing rules exist. type: string pattern: ^-?\d+\.\d{6}$ margin_pct: description: >- margin_usd / billable_usd × 100 (gross margin), two decimals; null when billable_usd is zero. Present only when pricing rules exist. nullable: true type: number priced: type: boolean description: >- True when every request in this row matched a pricing rule. False when some usage was counted at cost (no matching rule). required: - requests - prompt_tokens - completion_tokens - cost_usd - priced additionalProperties: false description: Sum over every tagged customer in the period. required: - period - currency - has_pricing_rules - truncated - customers - untagged - totals additionalProperties: false CustomerUsageError: type: object properties: error: type: object properties: message: type: string type: type: string enum: - invalid_request_error - authentication_error - request_forbidden - rate_limit_error - server_error param: nullable: true type: string code: type: string required: - message - type - param - code additionalProperties: false required: - error additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your AI Reserve API key (aireserve_api_…) from the API Keys page in the portal (https://portal.aireserve.com/keys). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.