> ## 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. `request_headers` carries the HTTP headers of the request — what the gateway received, and what it returned (the rate-limit state we reported, the request id, the routing disclosure; never the provider's own set). Credentials are replaced at capture: `Authorization`, `x-api-key`, `api-key`, `x-goog-api-key` and cookies report their NAME with a `[redacted]` value, so "you sent no Authorization header" stays distinguishable from "you sent one". The client-IP forwarding chain is not reported. NULL when the request log no longer holds the record — the rest of the payload answers regardless. `request_bodies` carries the prompt and completion themselves, and is NULL unless the key that made the request has opted in to exposing them — its own policy governs, not the caller's. It cannot be enabled for an organisation with zero data retention on, which is also why a ZDR org has none to show. Where PII redaction is enabled this is the REDACTED copy; the raw body is never stored. A body over the size cap reports `truncated: true` with its original size rather than being silently shortened. `video_task` carries the current status and result of the video generation task a `POST /v1/video/generations` request created — the stored response body only ever shows the submit's `queued`. Read from our records; it never polls the provider. NULL for any other request. No provider-side diagnostic is ever included. 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. `request_headers` carries the HTTP headers of the request — what the gateway received, and what it returned (the rate-limit state we reported, the request id, the routing disclosure; never the provider's own set). Credentials are replaced at capture: `Authorization`, `x-api-key`, `api-key`, `x-goog-api-key` and cookies report their NAME with a `[redacted]` value, so "you sent no Authorization header" stays distinguishable from "you sent one". The client-IP forwarding chain is not reported. NULL when the request log no longer holds the record — the rest of the payload answers regardless. `request_bodies` carries the prompt and completion themselves, and is NULL unless the key that made the request has opted in to exposing them — its own policy governs, not the caller's. It cannot be enabled for an organisation with zero data retention on, which is also why a ZDR org has none to show. Where PII redaction is enabled this is the REDACTED copy; the raw body is never stored. A body over the size cap reports `truncated: true` with its original size rather than being silently shortened. `video_task` carries the current status and result of the video generation task a `POST /v1/video/generations` request created — the stored response body only ever shows the submit's `queued`. Read from our records; it never polls the provider. NULL for any other request. No provider-side diagnostic is ever included. 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 - 2026-09 default: 2026-08 example: 2026-09 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'. routing_chain: anyOf: - $ref: '#/components/schemas/RoutingChainOut' - type: 'null' description: >- The per-attempt waterfall (MESH-863). NULL when the request took one attempt, so there is nothing to draw. request_headers: anyOf: - $ref: '#/components/schemas/RequestHeadersOut' - type: 'null' description: >- The HTTP headers of the request, as the gateway received and returned them (MESH-835). NULL when the request log no longer holds the record, or is unreachable — the rest of the payload answers regardless. request_bodies: anyOf: - $ref: '#/components/schemas/RequestBodiesOut' - type: 'null' description: >- The request and response BODIES, when the key or its org has opted in to storing them (MESH-856). NULL by default: body logging is off unless enabled, cannot be enabled under zero data retention, and expires on its own retention window before the rest of this payload does. video_task: anyOf: - $ref: '#/components/schemas/RequestVideoTaskOut' - type: 'null' description: >- The video generation task this request created, with its current status and result. NULL for any other request. 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 service_tier: anyOf: - type: string - type: 'null' title: Service Tier cost_breakdown: anyOf: - $ref: '#/components/schemas/CostBreakdownOut' - type: 'null' 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 tags: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Tags 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 tags: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Tags type: object required: - request_id - created_at - key_id - model - failure_stage - error_code - status_code - path - latency_ms title: RejectionOut RoutingChainOut: properties: hops: items: $ref: '#/components/schemas/RoutingHopOut' type: array title: Hops attempt_count: type: integer title: Attempt Count retry_count: type: integer title: Retry Count description: attempt_count - 1. fallback_count: type: integer title: Fallback Count description: >- Hops that changed provider, model, or credential — a retry of the same pair on the same key is not a fallback. failed_attempt_latency_ms: anyOf: - type: integer - type: 'null' title: Failed Attempt Latency Ms description: >- Upstream time spent on attempts that did not serve — retries included, so it is NOT the same as fallback time. NULL when nothing was retried, or when no failed attempt recorded a duration; 0 is a measurement. total_ms: anyOf: - type: integer - type: 'null' title: Total Ms description: The request's own latency. type: object required: - hops - attempt_count - retry_count - fallback_count title: RoutingChainOut description: >- The per-attempt waterfall for one request, plus the figures drawn beside it. RequestHeadersOut: properties: request_id: type: string title: Request Id captured_at: type: string title: Captured At description: When the gateway wrote this record. method: anyOf: - type: string - type: 'null' title: Method path: anyOf: - type: string - type: 'null' title: Path status_code: anyOf: - type: integer - type: 'null' title: Status Code retention_days: type: integer title: Retention Days description: How far back this endpoint can resolve a request id. request: additionalProperties: type: string type: object title: Request description: >- Headers the caller sent. A credential's name is reported with a `[redacted]` value — its presence is visible, its value never stored. The client-IP forwarding chain is not reported. response: additionalProperties: type: string type: object title: Response description: >- Headers the gateway returned — not the upstream provider's set, which is never exposed. type: object required: - request_id - captured_at - retention_days title: RequestHeadersOut description: The headers of one request, as the gateway received and returned them. RequestBodiesOut: properties: request_id: type: string title: Request Id captured_at: type: string title: Captured At description: When the gateway wrote this record. method: anyOf: - type: string - type: 'null' title: Method path: anyOf: - type: string - type: 'null' title: Path status_code: anyOf: - type: integer - type: 'null' title: Status Code model: anyOf: - type: string - type: 'null' title: Model stream: type: boolean title: Stream description: >- True when the response was an SSE stream, in which case `response.text` is the frame transcript rather than a JSON body — unless the transcript was large enough to be held outside the record, when `response.content` carries a reference to it instead. default: false retention_days: type: integer title: Retention Days description: >- How far back this endpoint resolves a request id. Bodies have no separate window — they are readable for as long as the request is. policy_source: anyOf: - type: string - type: 'null' title: Policy Source description: >- Which tier granted access: `inline` (the serving key's own policy), `org_default`, or `admin_override` — an operator read, which is not governed by either. request: anyOf: - $ref: '#/components/schemas/StoredBody' - type: 'null' description: >- What the caller sent. Where PII redaction was enabled this is the REDACTED copy — the raw body was never stored. Null when the policy asked for responses only, or when nothing was stored for this request. response: anyOf: - $ref: '#/components/schemas/StoredBody' - type: 'null' description: What the gateway returned. type: object required: - request_id - captured_at - retention_days title: RequestBodiesOut description: The bodies of one request, as the gateway received and returned them. RequestVideoTaskOut: properties: task_id: type: string title: Task Id status: type: string title: Status description: queued | running | succeeded | failed | expired | cancelled. video_url: anyOf: - type: string - type: 'null' title: Video Url description: Signed URL of the generated video. Expires. last_frame_url: anyOf: - type: string - type: 'null' title: Last Frame Url error_code: anyOf: - type: string - type: 'null' title: Error Code error_message: anyOf: - type: string - type: 'null' title: Error Message duration: anyOf: - type: integer - type: 'null' title: Duration description: Requested length, in seconds. resolution: anyOf: - type: string - type: 'null' title: Resolution billed_seconds: anyOf: - type: number - type: 'null' title: Billed Seconds billed_resolution: anyOf: - type: string - type: 'null' title: Billed Resolution settled: type: boolean title: Settled description: Usage for the task has been billed. created_at: type: string format: date-time title: Created At updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At type: object required: - task_id - status - settled - created_at title: RequestVideoTaskOut description: >- Customer-safe view of a video task: error text scrubbed, no provider fields. 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 CostBreakdownOut: properties: lines: items: $ref: '#/components/schemas/CostLineOut' type: array title: Lines subtotal_usd: type: string title: Subtotal Usd discount_pct: anyOf: - type: string - type: 'null' title: Discount Pct discount_usd: type: string title: Discount Usd tool_fee_usd: type: string title: Tool Fee Usd cost_usd: type: string title: Cost Usd type: object required: - lines - subtotal_usd - discount_pct - discount_usd - tool_fee_usd - cost_usd title: CostBreakdownOut description: >- How `cost_usd` was reached. Rates are our sell rates; nothing upstream is exposed. RoutingHopOut: properties: attempt_no: type: integer title: Attempt No kind: type: string title: Kind description: >- 'initial' | 'retry' (same provider and model) | 'provider_fallback' | 'model_fallback'. A rotation onto a different platform credential reads as 'retry' — which credential served is internal. provider: anyOf: - type: string - type: 'null' title: Provider description: >- The upstream this hop was attempted against — see `served` for which hop ended the request. Present on failed hops too, so a fallback's abandoned primary is named. Treat as unstable: whether the upstream is exposed at all is under review. model: type: string title: Model 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 duration_ms: anyOf: - type: integer - type: 'null' title: Duration Ms description: >- This hop's upstream time. Exact on a failed hop. On the SERVING hop it is derived (the request's provider time less every failed attempt's) and is therefore an upper bound: it still includes any backoff waited between attempts, which no stored column separates. served: type: boolean title: Served description: True on the one hop the request ended on. byok_fallback: type: boolean title: Byok Fallback description: >- This attempt began on the caller's own credential and completed on ours (X-BYOK-Fallback-Triggered). default: false type: object required: - attempt_no - kind - provider - model - status - served title: RoutingHopOut description: >- One attempt in a request's routing chain (MESH-863), oldest first. ``kind`` is what the customer is actually asking when a request was slow: was the same upstream retried, did we move to another one, or was the model swapped. Rendering those identically hides the answer. A BYOK credential fallback is a fifth event but NOT a ``kind``: it happens inside a single attempt, so it can coincide with any of them. It rides on ``byok_fallback`` instead, or a hop that both changed provider and fell back from the caller's credential could only report one of the two. StoredBody: properties: truncated: type: boolean title: Truncated description: >- True when the body exceeded the response cap and only its head is returned. Never inferred from a length — a body this large is otherwise indistinguishable from one that was genuinely this size. bytes: type: integer title: Bytes description: Size of the stored body, before this cap. stored_bytes: anyOf: - type: integer - type: 'null' title: Stored Bytes description: How much is returned. Only present when truncated. content: anyOf: - {} - type: 'null' title: Content description: The body as JSON, when it was stored as JSON and fits. text: anyOf: - type: string - type: 'null' title: Text description: >- The body as text — a non-JSON body, a stream transcript, or the head of one that was truncated. type: object required: - truncated - bytes title: StoredBody description: One side's body, and whether this response carries all of it. CostLineOut: properties: kind: type: string enum: - input - cache_read - cache_write - cache_write_1h - output - reasoning - audio_input - audio_output - cached_audio_input title: Kind tokens: type: integer title: Tokens rate_per_1m_usd: type: string title: Rate Per 1M Usd amount_usd: type: string title: Amount Usd type: object required: - kind - tokens - rate_per_1m_usd - amount_usd title: CostLineOut 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 `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.