> ## 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. > Get every upstream attempt the AI Gateway made for one client request, ordered by attempt number. # Get the upstream attempts of one AI Gateway request ## OpenAPI ````yaml openapi/ai-gateway.yaml GET /usage/requests/{requestId} 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 or a charge of the saved card, and read purchase/transaction history. - 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 Models description: >- Read-only listing of AI Gateway models available to the authenticated account. - 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/requests/{requestId}: get: tags: - AI Gateway Usage summary: Get the upstream attempts of one AI Gateway request description: | Return every upstream attempt the AI Gateway made for one client request, ordered by attempt number. Read-only and account-scoped. The AI Gateway states the request ID on every response it sends, in the `Ngrok-AIG-Request-Id` header. Pass that value here to see which providers and models the request tried, in what order, and which one served it. operationId: GetAIGatewayRequestAttempts parameters: - name: requestId in: path required: true description: The request ID from the `Ngrok-AIG-Request-Id` response header. schema: type: string responses: '200': description: Every upstream attempt for the request. content: application/json: schema: $ref: '#/components/schemas/AIGatewayRequest' default: $ref: '#/components/responses/Error' components: schemas: AIGatewayRequest: type: object additionalProperties: false required: - uri - requestId - attempts properties: uri: type: string description: URI of this request resource. requestId: type: string description: The request ID this resource describes. attempts: type: array description: Every upstream attempt, ordered by attempt number. items: $ref: '#/components/schemas/AIGatewayRequestAttempt' AIGatewayRequestAttempt: type: object additionalProperties: false required: - event - served - completion properties: event: $ref: '#/components/schemas/AIGatewayUsageEvent' served: type: boolean description: >- Whether this attempt produced the response the client received. At most one attempt of a request is served. retryAction: $ref: '#/components/schemas/AIGatewayRetryAction' completion: $ref: '#/components/schemas/AIGatewayAttemptCompletion' requestDurationMs: type: integer format: int64 nullable: true description: >- Time from the gateway receiving the client request to the attempt completing, in milliseconds. upstreamDurationMs: type: integer format: int64 nullable: true description: Time the upstream provider took to answer, in milliseconds. timeToFirstTokenMs: type: integer format: int64 nullable: true description: >- Time to the first streamed token, in milliseconds. Null for a non-streaming attempt. 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 AIGatewayUsageEvent: type: object additionalProperties: false required: - id - eventTime - requestId - accessKeyId - provider - providerDisplayName - model - modelDisplayName - attemptNumber - isFinalAttempt - statusCode - timedOut - isError - isStreaming - stopReason - inputTokens - outputTokens - cacheReadTokens - cacheWriteTokens - cacheWrite5mTokens - cacheWrite1hTokens - reasoningTokens - inputTokensEstimate - outputTokensEstimate - usageEstimated - processingFeeInputTokens - processingFeeOutputTokens - processingFeeUsageSource - toolUsePromptTokens - totalCost - inputTokenCost - outputTokenCost - ngrokProcessingFee - cacheReadCost - cacheWriteCost - cacheWrite5mCost - cacheWrite1hCost - 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. cacheWriteTokens: type: integer format: int64 description: Tokens written to the provider cache. cacheWrite5mTokens: type: integer format: int64 description: Tokens written to the provider cache with a 5-minute TTL. cacheWrite1hTokens: type: integer format: int64 description: Tokens written to the provider cache with a 1-hour TTL. reasoningTokens: type: integer format: int64 description: Reasoning tokens reported by the provider. inputTokensEstimate: type: integer format: int64 description: Input tokens counted by ngrok's tokenizer. outputTokensEstimate: type: integer format: int64 description: Output tokens counted by ngrok's tokenizer. usageEstimated: type: boolean description: >- True when the provider reported no usage and the cost was derived from inputTokensEstimate and outputTokensEstimate. The provider-reported token fields are all zero on these attempts, so display the estimates instead. processingFeeInputTokens: type: integer format: int64 description: Token count billed as ngrok processing-fee input. processingFeeOutputTokens: type: integer format: int64 description: Token count billed as ngrok processing-fee output. processingFeeUsageSource: type: string description: >- `provider` when the processing fee used reported usage, `estimate` when it used ngrok's tokenizer, or `unavailable` when the event did not record the source. `notApplicable` when no processing fee was billed. enum: - provider - estimate - unavailable - notApplicable x-enum-varnames: - ProcessingFeeUsageSourceProvider - ProcessingFeeUsageSourceEstimate - ProcessingFeeUsageSourceUnavailable - ProcessingFeeUsageSourceNotApplicable toolUsePromptTokens: type: integer format: int64 description: Hosted-tool prompt tokens counted as processing-fee input. totalCost: type: string description: >- Total cost in US dollars as a decimal string (5-place fractional precision). inputTokenCost: type: string description: >- Base input-token cost, excluding cache reads and writes, in US dollars as a decimal string (5-place fractional precision). outputTokenCost: type: string description: >- Output-token cost in US dollars as a decimal string (5-place fractional precision). ngrokProcessingFee: type: string description: >- ngrok processing fee in US dollars as a decimal string (5-place fractional precision). cacheReadCost: type: string description: >- Cache-read cost in US dollars as a decimal string (5-place fractional precision). cacheWriteCost: type: string description: >- Cache-write cost in US dollars as a decimal string (5-place fractional precision). cacheWrite5mCost: type: string description: >- 5-minute cache-write cost in US dollars as a decimal string (5-place fractional precision). cacheWrite1hCost: type: string description: >- 1-hour cache-write 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. AIGatewayRetryAction: type: string description: > The verdict the gateway's retry loop reached after one attempt, which says why it moved on. Absent for an attempt the gateway recorded before it stored the verdict. enum: - succeeded - next_key - next_quota_pool - next_backend - managed_fallback - retry_same_backend - fail_fast - exhausted AIGatewayAttemptCompletion: type: string description: >- How one upstream attempt finished. `stream_failed` means the stream broke after the first token reached the client. enum: - succeeded - failed - timed_out - stream_failed - unknown responses: Error: description: API error response. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer ````