> ## 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 for one end customer, by feature or day > The same figures for a single end customer, broken down by the `x-aireserve-feature` tag (default) or by UTC day — the call to make when a customer asks what they owe. Customer ids are opaque: an id you have never tagged simply returns zeros, so ids cannot be probed. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/customers/{customerId}/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/{customerId}/usage: get: tags: - Customers summary: Usage for one end customer, by feature or day description: >- The same figures for a single end customer, broken down by the `x-aireserve-feature` tag (default) or by UTC day — the call to make when a customer asks what they owe. Customer ids are opaque: an id you have never tagged simply returns zeros, so ids cannot be probed. operationId: getCustomerUsage parameters: - name: customerId in: path required: true description: >- Your end-customer id, URL-encoded, exactly as tagged on requests (1–128 printable characters). schema: type: string minLength: 1 maxLength: 128 - 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 - name: group_by in: query required: false description: '`feature` (default) or `day`.' schema: type: string enum: - feature - day default: feature responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CustomerUsageReport' '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: CustomerUsageReport: type: object properties: customer_id: type: string 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. group_by: type: string enum: - feature - day groups: type: array items: type: object properties: feature: description: >- When group_by=feature: the x-aireserve-feature tag, or null for requests that carried none. nullable: true type: string day: description: 'When group_by=day: the UTC calendar day, YYYY-MM-DD.' type: string 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: >- Highest cost first for features; chronological for days. Empty for an unknown customer id. 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 the customer's usage in the period. monthly_flat_charges: type: array items: type: object properties: month: type: string description: UTC calendar month, YYYY-MM. day: type: string description: >- The day the fee was booked on — the first day in the month with matched usage. amount_usd: type: string pattern: ^-?\d+\.\d{6}$ description: USD amount as a six-decimal string. Never a float. required: - month - day - amount_usd additionalProperties: false description: >- Monthly flat fees booked in the period, one per calendar month with matched usage. Already included in billable_usd. required: - customer_id - period - currency - has_pricing_rules - truncated - group_by - groups - totals - monthly_flat_charges 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.