> ## Documentation Index
> Fetch the complete documentation index at: https://developers.meshapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Request

> Look up one request by the id returned in its `X-Request-Id` response header.

Reports what the gateway knows about that request: the model and provider that
served it, status, latency, tokens, cost, and every attempt made — so a retry
or a fallback to another target is visible rather than inferred.

Requests refused before any model was called (rate limit, spend cap, empty
balance, model access) write no usage row, and are served from the request log
with `outcome: "rejected"`.

Two surfaces are not resolvable here, because their usage is not recorded
against the HTTP request's id: `/v1/chat/compare`, whose fan-out is recorded
per model under a derived id, and `/v1/batches`, whose usage is recorded
against the batch id — use `GET /v1/batches/{batch_id}` for those.

Resolvable for **90 days**. Older ids return 404, as does an id belonging to
another account — existence is never confirmed across tenants.

Prompts and completions are never included; neither is any provider-side
diagnostic. Error text is the same scrubbed message the original response
carried.



## OpenAPI

````yaml /api/openapi.json get /v1/usage/requests/{request_id}
openapi: 3.1.0
info:
  title: MeshAPI
  description: One key, all AI models.
  version: 0.1.0
servers:
  - url: https://api.meshapi.ai
security:
  - BearerAuth: []
paths:
  /v1/usage/requests/{request_id}:
    get:
      tags:
        - Usage
      summary: Get Request
      description: >-
        Look up one request by the id returned in its `X-Request-Id` response
        header.


        Reports what the gateway knows about that request: the model and
        provider that

        served it, status, latency, tokens, cost, and every attempt made — so a
        retry

        or a fallback to another target is visible rather than inferred.


        Requests refused before any model was called (rate limit, spend cap,
        empty

        balance, model access) write no usage row, and are served from the
        request log

        with `outcome: "rejected"`.


        Two surfaces are not resolvable here, because their usage is not
        recorded

        against the HTTP request's id: `/v1/chat/compare`, whose fan-out is
        recorded

        per model under a derived id, and `/v1/batches`, whose usage is recorded

        against the batch id — use `GET /v1/batches/{batch_id}` for those.


        Resolvable for **90 days**. Older ids return 404, as does an id
        belonging to

        another account — existence is never confirmed across tenants.


        Prompts and completions are never included; neither is any provider-side

        diagnostic. Error text is the same scrubbed message the original
        response

        carried.
      operationId: get_request
      parameters:
        - name: request_id
          in: path
          required: true
          schema:
            type: string
            title: Request Id
        - in: header
          name: X-Mesh-Version
          required: false
          schema:
            type: string
            enum:
              - 2026-08
            default: 2026-08
          example: 2026-08
          description: >-
            Dated version of the API contract to pin this request to. Omit it
            and the request is served under `2026-08` — the oldest supported
            version, so an existing integration is never moved by a release. A
            malformed or unsupported value is rejected with `400
            invalid_api_version` rather than falling back silently. The version
            actually served is echoed as `X-Mesh-Version` on every response,
            including errors.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestLookupOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerAuth: []
components:
  schemas:
    RequestLookupOut:
      properties:
        request_id:
          type: string
          title: Request Id
        outcome:
          type: string
          title: Outcome
          description: >-
            'success' | 'error' when a model was reached, 'rejected' when a gate
            refused the request before any model was called, 'pending' while the
            request's own usage row has not landed yet, and 'unknown' once it is
            too old to still be arriving — the attempts are reported either way.
        retention_days:
          type: integer
          title: Retention Days
          description: How far back this endpoint can resolve a request id.
        ambiguous:
          type: boolean
          title: Ambiguous
          description: >-
            The id addressed more than one request, so `attempts` is omitted
            rather than guessed at. Only possible for requests made before the
            gateway began minting the id itself.
          default: false
        event:
          anyOf:
            - $ref: '#/components/schemas/UsageEventOut'
            - type: 'null'
          description: 'The request itself: the attempt that served it.'
        attempts:
          items:
            $ref: '#/components/schemas/UsageEventOut'
          type: array
          title: Attempts
          description: Every attempt including retried failures, oldest first.
        attempt_count:
          type: integer
          title: Attempt Count
          default: 0
        retry_count:
          type: integer
          title: Retry Count
          description: attempt_count - 1.
          default: 0
        related_events:
          items:
            $ref: '#/components/schemas/UsageEventOut'
          type: array
          title: Related Events
          description: Other billed rows this request produced (e.g. a memory embedding).
        matches:
          items:
            $ref: '#/components/schemas/UsageEventOut'
          type: array
          title: Matches
          description: Populated only when `ambiguous`.
        rejection:
          anyOf:
            - $ref: '#/components/schemas/RejectionOut'
            - type: 'null'
          description: Populated only when `outcome` is 'rejected'.
      type: object
      required:
        - request_id
        - outcome
        - retention_days
      title: RequestLookupOut
      description: >-
        Everything we can say about one request id (MESH-768).


        Carries ``UsageEventOut``, never ``UsageEventDetailOut`` —
        `error_detail`,

        `provider_error_code`, `provider_request_id`, `upstream_status`,

        `provider_requested` and `ip_address` exist only on the admin subclass,
        so no

        provider internal can reach a customer through this shape.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UsageEventOut:
      properties:
        id:
          type: string
          title: Id
        key_id:
          type: string
          title: Key Id
        key_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Key Label
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        end_user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: End User Id
        request_id:
          type: string
          title: Request Id
        model:
          type: string
          title: Model
        model_name:
          type: string
          title: Model Name
        model_provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Provider
        stream:
          type: boolean
          title: Stream
        prompt_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Prompt Tokens
        completion_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Completion Tokens
        total_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Tokens
        cost_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Cost Usd
        latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Latency Ms
        tokens_per_second:
          anyOf:
            - type: number
            - type: 'null'
          title: Tokens Per Second
        provider_latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Provider Latency Ms
        platform_latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Platform Latency Ms
        ttft_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Ttft Ms
        status:
          type: string
          title: Status
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
        error_category:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Category
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
        failure_stage:
          anyOf:
            - type: string
            - type: 'null'
          title: Failure Stage
        created_at:
          type: string
          title: Created At
        images_generated:
          anyOf:
            - type: integer
            - type: 'null'
          title: Images Generated
        model_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Type
        is_byok:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Byok
        byok_key_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Byok Key Id
        byok_key_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Byok Key Label
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
        fallback_triggered:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Fallback Triggered
        platform_fee_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Platform Fee Usd
        image_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Image Tokens
        member_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Member Name
        member_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Member Email
        attempt_no:
          anyOf:
            - type: integer
            - type: 'null'
          title: Attempt No
        is_retry_attempt:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Retry Attempt
        routing_fallback:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Routing Fallback
        model_requested:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Requested
      type: object
      required:
        - id
        - key_id
        - key_label
        - request_id
        - model
        - model_name
        - model_provider
        - stream
        - prompt_tokens
        - completion_tokens
        - total_tokens
        - cost_usd
        - latency_ms
        - tokens_per_second
        - status
        - error_code
        - created_at
      title: UsageEventOut
    RejectionOut:
      properties:
        request_id:
          type: string
          title: Request Id
        created_at:
          type: string
          title: Created At
        key_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Key Id
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
        failure_stage:
          anyOf:
            - type: string
            - type: 'null'
          title: Failure Stage
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
        status_code:
          anyOf:
            - type: integer
            - type: 'null'
          title: Status Code
        path:
          anyOf:
            - type: string
            - type: 'null'
          title: Path
        latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Latency Ms
      type: object
      required:
        - request_id
        - created_at
        - key_id
        - model
        - failure_stage
        - error_code
        - status_code
        - path
        - latency_ms
      title: RejectionOut
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Enter your MeshAPI key (`rsk_...`) or, for the admin-keys endpoints, a
        dashboard session token — sent as `Authorization: Bearer <token>`.

````