> ## Documentation Index > Fetch the complete documentation index at: https://docs.aixy-gateway.com/llms.txt > Use this file to discover all available pages before exploring further. # Usage > Read this gateway key's retained seven-day usage and applicable budget cycles. Authenticate with the same project-scoped Aixy key used for inference. Only this key's totals and applicable budget aggregates are returned, without other keys, users, credentials or request content. This read never runs inference or reserves budget and remains available when a hard budget is exhausted. Budget scopes overlap: do not sum their limits or spend. Shared budgets include other callers' aggregate spend. Recorded spend is attributed analytics, not a provider invoice; it may lag enforcement or cover only retained events. Hard availability separately includes reservations. Null usage/balances mean unavailable, never zero. The response is private; clients should poll no faster than once a minute. ## OpenAPI ````yaml /openapi.json get /v1/usage openapi: 3.1.0 info: title: Aixy Gateway API version: 0.1.0 description: >- Route requests to configured AI providers through OpenAI- and Anthropic-compatible APIs. Aixy applies project access, model policies, guardrails, routing, budgets, and usage attribution before forwarding inference traffic. servers: - url: https://api.aixy-gateway.com description: Aixy production gateway security: [] tags: - name: operations description: Check process liveness and traffic readiness. - name: authentication description: Authenticate trusted server-side clients. - name: organizations description: Manage the organization and its lifecycle. - name: projects description: Create projects and manage project membership. - name: users description: Manage organization users, roles, and invitations. - name: teams description: Manage teams and team membership. - name: api-keys description: Manage project-scoped gateway API keys. - name: provider-credentials description: Manage organization and project provider credentials. - name: provider-catalog description: Discover providers supported by the gateway. - name: provider-models description: Discover and control models exposed by configured providers. - name: routing description: Configure stable model aliases, routing strategies, and fallbacks. - name: guardrails description: Configure prompt and sensitive-data protection policies. - name: identity connections description: Configure tenant-scoped enterprise identity federation. - name: playground description: Exercise configured models through the gateway. - name: cost-control description: Inspect spend and enforce budgets across tenant scopes. - name: metrics description: Inspect usage, token, latency, and error metrics. - name: activity description: Diagnose individual model requests and manage opt-in content capture. - name: monitors description: Configure operational monitors and notification channels. - name: audit description: Query, verify, and export the organization audit log. - name: telemetry exports description: Export telemetry to organization-owned destinations. - name: billing description: Inspect and manage the organization subscription. - name: models description: List models available to a project-scoped gateway API key. - name: inference description: Run model inference through the Aixy data plane. - name: pricing description: Manage versioned pricing attribution rules. - name: system description: Discover gateway capabilities and providers. - name: MCP beta description: Mcp beta operations exposed by the gateway. - name: cost-optimization description: Cost optimization operations exposed by the gateway. - name: custom domains description: Custom domains operations exposed by the gateway. - name: data processing description: Data processing operations exposed by the gateway. - name: feature flags description: Feature flags operations exposed by the gateway. - name: privacy description: Privacy operations exposed by the gateway. - name: roles description: Roles operations exposed by the gateway. paths: /v1/usage: get: tags: - metrics summary: Usage description: >- Read this gateway key's retained seven-day usage and applicable budget cycles. Authenticate with the same project-scoped Aixy key used for inference. Only this key's totals and applicable budget aggregates are returned, without other keys, users, credentials or request content. This read never runs inference or reserves budget and remains available when a hard budget is exhausted. Budget scopes overlap: do not sum their limits or spend. Shared budgets include other callers' aggregate spend. Recorded spend is attributed analytics, not a provider invoice; it may lag enforcement or cover only retained events. Hard availability separately includes reservations. Null usage/balances mean unavailable, never zero. The response is private; clients should poll no faster than once a minute. operationId: get_gateway_key_usage responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/KeyUsageResponse' '401': description: Authentication is required or invalid. content: application/json: schema: $ref: '#/components/schemas/GatewayErrorResponse' '413': description: The request body exceeds the endpoint limit. content: application/json: schema: $ref: '#/components/schemas/GatewayErrorResponse' '503': description: The control-plane capability is unavailable. content: application/json: schema: $ref: '#/components/schemas/GatewayErrorResponse' 4XX: description: The request was rejected by validation or authorization. content: application/json: schema: $ref: '#/components/schemas/GatewayErrorResponse' security: - GatewayApiKey: [] components: schemas: KeyUsageResponse: properties: object: type: string const: key.usage title: Object default: key.usage as_of: type: string title: As Of currency: type: string const: USD title: Currency default: USD key: $ref: '#/components/schemas/UsageKeyResponse' usage: anyOf: - $ref: '#/components/schemas/KeyUsageTotalsResponse' - type: 'null' budgets: items: $ref: '#/components/schemas/PersonalBudgetResponse' type: array title: Budgets type: object required: - as_of - key - usage - budgets title: KeyUsageResponse GatewayErrorResponse: properties: error: $ref: '#/components/schemas/GatewayErrorDetail' type: object required: - error title: GatewayErrorResponse UsageKeyResponse: properties: id: type: string title: Id name: anyOf: - type: string - type: 'null' title: Name project_id: type: string title: Project Id project_name: anyOf: - type: string - type: 'null' title: Project Name type: object required: - id - name - project_id - project_name title: UsageKeyResponse KeyUsageTotalsResponse: properties: window: type: string const: 7d title: Window default: 7d requests: type: integer title: Requests input_tokens: type: integer title: Input Tokens output_tokens: type: integer title: Output Tokens total_tokens: type: integer title: Total Tokens spend_usd: anyOf: - type: number - type: 'null' title: Spend Usd attributed_requests: type: integer title: Attributed Requests estimated_requests: type: integer title: Estimated Requests provider_reported_requests: type: integer title: Provider Reported Requests reconciled_requests: type: integer title: Reconciled Requests partial_requests: type: integer title: Partial Requests type: object required: - requests - input_tokens - output_tokens - total_tokens - spend_usd - attributed_requests - estimated_requests - provider_reported_requests - reconciled_requests - partial_requests title: KeyUsageTotalsResponse PersonalBudgetResponse: properties: id: type: string title: Id object: type: string const: cost.personal_budget title: Object default: cost.personal_budget scope: $ref: '#/components/schemas/BudgetScope' target_id: anyOf: - type: string - type: 'null' title: Target Id target_name: type: string title: Target Name interval: $ref: '#/components/schemas/BudgetInterval' limit_usd: type: string title: Limit Usd warning_threshold_percent: type: integer title: Warning Threshold Percent enforcement: $ref: '#/components/schemas/BudgetEnforcement' allocation: $ref: '#/components/schemas/BudgetAllocation' shared: type: boolean title: Shared applies_to: items: $ref: '#/components/schemas/BudgetUsageScopeResponse' type: array title: Applies To spend_usd: anyOf: - type: string - type: 'null' title: Spend Usd remaining_usd: anyOf: - type: string - type: 'null' title: Remaining Usd utilization_percent: anyOf: - type: number - type: 'null' title: Utilization Percent state: type: string enum: - healthy - warning - exceeded - unknown title: State starts_at: anyOf: - type: string - type: 'null' title: Starts At resets_at: anyOf: - type: string - type: 'null' title: Resets At spend_status: type: string enum: - available - unavailable title: Spend Status availability: $ref: '#/components/schemas/BudgetAvailabilityResponse' type: object required: - id - scope - target_id - target_name - interval - limit_usd - warning_threshold_percent - enforcement - allocation - shared - applies_to - spend_usd - remaining_usd - utilization_percent - state - starts_at - resets_at - spend_status - availability title: PersonalBudgetResponse GatewayErrorDetail: properties: code: type: string title: Code message: type: string title: Message details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details type: object required: - code - message title: GatewayErrorDetail BudgetScope: type: string enum: - organization - project - team - user - api_key title: BudgetScope BudgetInterval: type: string enum: - daily - weekly - monthly - lifetime title: BudgetInterval BudgetEnforcement: type: string enum: - monitor - hard title: BudgetEnforcement BudgetAllocation: type: string enum: - shared - per_user title: BudgetAllocation BudgetUsageScopeResponse: properties: api_key_id: type: string title: Api Key Id api_key_name: type: string title: Api Key Name project_id: type: string title: Project Id project_name: type: string title: Project Name team_id: anyOf: - type: string - type: 'null' title: Team Id team_name: anyOf: - type: string - type: 'null' title: Team Name type: object required: - api_key_id - api_key_name - project_id - project_name - team_id - team_name title: BudgetUsageScopeResponse BudgetAvailabilityResponse: properties: status: type: string enum: - available - unavailable - not_enforced title: Status spent_usd: anyOf: - type: string - type: 'null' title: Spent Usd reserved_usd: anyOf: - type: string - type: 'null' title: Reserved Usd remaining_usd: anyOf: - type: string - type: 'null' title: Remaining Usd type: object required: - status - spent_usd - reserved_usd - remaining_usd title: BudgetAvailabilityResponse securitySchemes: GatewayApiKey: type: http scheme: bearer bearerFormat: gak_… description: >- A project-scoped Aixy API key. Create keys in the dashboard and send the secret as a Bearer token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.