> ## Documentation Index > Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > List per-attempt AI Gateway usage events for the authenticated account. # List AI Gateway usage events ## OpenAPI ````yaml openapi/ai-gateway.yaml GET /usage openapi: 3.0.3 info: title: AI Gateway APIs version: 0.1.0 description: | Control-plane HTTP APIs served by the ai-gateway-control service. servers: - url: https://api.ngrok.ai security: - bearerAuth: [] tags: - name: AI Gateway Access Key Configurations description: Manage reusable access key configurations (scope and routing rules). - name: AI Gateway Access Keys description: Manage ngrok-managed access keys associated with AI Gateway endpoints. - name: AI Gateway Configuration description: >- Manage per-account AI Gateway configuration (timeouts, token caps, metadata). - name: AI Gateway API Keys description: Manage customer-facing AI Gateway API Keys. - name: AI Gateway Credits description: Purchase AI Gateway credits via Stripe Checkout. - name: AI Gateway Providers description: Manage AI Gateway providers and the models they expose. - name: AI Gateway Custom Providers description: Manage custom AI Gateway providers and the models they expose. - name: AI Gateway Provider Keys description: Manage provider keys attached to AI Gateway managed access keys. - name: AI Gateway Usage description: >- Read-only AI Gateway usage events and aggregated usage overview for the authenticated account. paths: /usage: get: tags: - AI Gateway Usage summary: List AI Gateway usage events description: | List per-attempt AI Gateway usage events for the authenticated account. Read-only and account-scoped. Filterable by time range and optionally by access key. Paged with an opaque cursor. operationId: ListAIGatewayUsage parameters: - name: startTime in: query required: true description: Only return events with `eventTime` >= this RFC3339 timestamp. schema: type: string format: date-time - name: endTime in: query required: false description: >- Only return events with `eventTime` <= this RFC3339 timestamp. Defaults to now. schema: type: string format: date-time - name: accessKeyId in: query required: false description: Filter results to a single AI Gateway access key. schema: type: string - name: includeRetries in: query required: false description: >- When true, include retry attempts in addition to the request-level terminal attempt. Defaults to false. schema: type: boolean default: false - name: cursor in: query required: false description: >- Cursor from a previous response's `nextPageUri`. Pass to fetch the next page. schema: type: string - $ref: '#/components/parameters/Limit' responses: '200': description: A page of AI Gateway usage events. content: application/json: schema: $ref: '#/components/schemas/AIGatewayUsageList' default: $ref: '#/components/responses/Error' components: parameters: Limit: name: limit in: query required: false description: >- Maximum number of items to return. Defaults to 100 and may not exceed 100. schema: type: integer format: int32 minimum: 1 maximum: 100 schemas: AIGatewayUsageList: type: object additionalProperties: false required: - aiGatewayUsage - uri properties: aiGatewayUsage: type: array description: A page of AI Gateway usage events, ordered newest first. items: $ref: '#/components/schemas/AIGatewayUsageEvent' uri: type: string description: URI of this list resource. nextPageUri: type: string nullable: true description: URI of the next page of results, or null if there is no next page. AIGatewayUsageEvent: type: object additionalProperties: false required: - id - eventTime - requestId - accessKeyId - provider - providerDisplayName - model - modelDisplayName - attemptNumber - isFinalAttempt - statusCode - timedOut - isError - isStreaming - stopReason - inputTokens - outputTokens - cacheReadTokens - reasoningTokens - totalCost - keySource properties: id: type: string description: Unique identifier for this attempt event. eventTime: type: string format: date-time description: Timestamp at which the upstream attempt completed. requestId: type: string description: ID linking attempts that belong to the same client request. accessKeyId: type: string description: The AI Gateway access key that originated the request. provider: type: string description: AI provider canonical ID, for example `openai`. providerDisplayName: type: string description: Human-readable provider name. model: type: string description: Model canonical ID, for example `gpt-4o-mini`. modelDisplayName: type: string description: Human-readable model name. attemptNumber: type: integer format: int32 description: 1-based attempt index in the retry chain. isFinalAttempt: type: boolean description: True if this was the terminal attempt for the request. statusCode: type: integer format: int32 description: HTTP status code returned by the upstream provider. timedOut: type: boolean description: True if the attempt timed out. isError: type: boolean description: True if this attempt was an error (timed out or HTTP 4xx/5xx). isStreaming: type: boolean description: True if the request was a streaming response. stopReason: type: string description: Provider-reported finish reason. inputTokens: type: integer format: int64 description: Provider-reported input tokens. outputTokens: type: integer format: int64 description: Provider-reported output tokens. cacheReadTokens: type: integer format: int64 description: Tokens read from the provider cache. reasoningTokens: type: integer format: int64 description: Reasoning tokens reported by the provider. totalCost: type: string description: >- Total cost in US dollars as a decimal string (5-place fractional precision). keySource: type: string description: >- Source of the provider credential. `ngrok` for managed keys, `user` for BYOK provider keys. providerKeyId: type: string description: The provider key used, when `keySource` is `user`. Absent otherwise. providerKeyDisplayName: type: string description: >- Redacted display form of the provider key, when `keySource` is `user`. Absent otherwise. Error: type: object additionalProperties: false required: - statusCode - msg - details properties: errorCode: type: string description: Stable ngrok error code when available. statusCode: type: integer format: int32 description: HTTP status code for this error. msg: type: string description: Human-readable error message. details: type: object description: Structured error details. additionalProperties: type: string responses: Error: description: API error response. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer ````