Get Request

curl --request GET \
  --url https://api.meshapi.ai/v1/usage/requests/{request_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.meshapi.ai/v1/usage/requests/{request_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.meshapi.ai/v1/usage/requests/{request_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.meshapi.ai/v1/usage/requests/{request_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.meshapi.ai/v1/usage/requests/{request_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "request_id": "<string>",
  "outcome": "<string>",
  "retention_days": 123,
  "ambiguous": false,
  "event": {
    "id": "<string>",
    "key_id": "<string>",
    "key_label": "<string>",
    "request_id": "<string>",
    "model": "<string>",
    "model_name": "<string>",
    "model_provider": "<string>",
    "stream": true,
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123,
    "cost_usd": "<string>",
    "latency_ms": 123,
    "tokens_per_second": 123,
    "status": "<string>",
    "error_code": "<string>",
    "created_at": "<string>",
    "user_id": "<string>",
    "end_user_id": "<string>",
    "provider_latency_ms": 123,
    "platform_latency_ms": 123,
    "ttft_ms": 123,
    "error_category": "<string>",
    "error_message": "<string>",
    "failure_stage": "<string>",
    "images_generated": 123,
    "model_type": "<string>",
    "is_byok": true,
    "byok_key_id": "<string>",
    "byok_key_label": "<string>",
    "provider": "<string>",
    "fallback_triggered": true,
    "platform_fee_usd": "<string>",
    "image_tokens": 123,
    "member_name": "<string>",
    "member_email": "<string>",
    "attempt_no": 123,
    "is_retry_attempt": true,
    "routing_fallback": true,
    "model_requested": "<string>"
  },
  "attempts": [
    {
      "id": "<string>",
      "key_id": "<string>",
      "key_label": "<string>",
      "request_id": "<string>",
      "model": "<string>",
      "model_name": "<string>",
      "model_provider": "<string>",
      "stream": true,
      "prompt_tokens": 123,
      "completion_tokens": 123,
      "total_tokens": 123,
      "cost_usd": "<string>",
      "latency_ms": 123,
      "tokens_per_second": 123,
      "status": "<string>",
      "error_code": "<string>",
      "created_at": "<string>",
      "user_id": "<string>",
      "end_user_id": "<string>",
      "provider_latency_ms": 123,
      "platform_latency_ms": 123,
      "ttft_ms": 123,
      "error_category": "<string>",
      "error_message": "<string>",
      "failure_stage": "<string>",
      "images_generated": 123,
      "model_type": "<string>",
      "is_byok": true,
      "byok_key_id": "<string>",
      "byok_key_label": "<string>",
      "provider": "<string>",
      "fallback_triggered": true,
      "platform_fee_usd": "<string>",
      "image_tokens": 123,
      "member_name": "<string>",
      "member_email": "<string>",
      "attempt_no": 123,
      "is_retry_attempt": true,
      "routing_fallback": true,
      "model_requested": "<string>"
    }
  ],
  "attempt_count": 0,
  "retry_count": 0,
  "related_events": [
    {
      "id": "<string>",
      "key_id": "<string>",
      "key_label": "<string>",
      "request_id": "<string>",
      "model": "<string>",
      "model_name": "<string>",
      "model_provider": "<string>",
      "stream": true,
      "prompt_tokens": 123,
      "completion_tokens": 123,
      "total_tokens": 123,
      "cost_usd": "<string>",
      "latency_ms": 123,
      "tokens_per_second": 123,
      "status": "<string>",
      "error_code": "<string>",
      "created_at": "<string>",
      "user_id": "<string>",
      "end_user_id": "<string>",
      "provider_latency_ms": 123,
      "platform_latency_ms": 123,
      "ttft_ms": 123,
      "error_category": "<string>",
      "error_message": "<string>",
      "failure_stage": "<string>",
      "images_generated": 123,
      "model_type": "<string>",
      "is_byok": true,
      "byok_key_id": "<string>",
      "byok_key_label": "<string>",
      "provider": "<string>",
      "fallback_triggered": true,
      "platform_fee_usd": "<string>",
      "image_tokens": 123,
      "member_name": "<string>",
      "member_email": "<string>",
      "attempt_no": 123,
      "is_retry_attempt": true,
      "routing_fallback": true,
      "model_requested": "<string>"
    }
  ],
  "matches": [
    {
      "id": "<string>",
      "key_id": "<string>",
      "key_label": "<string>",
      "request_id": "<string>",
      "model": "<string>",
      "model_name": "<string>",
      "model_provider": "<string>",
      "stream": true,
      "prompt_tokens": 123,
      "completion_tokens": 123,
      "total_tokens": 123,
      "cost_usd": "<string>",
      "latency_ms": 123,
      "tokens_per_second": 123,
      "status": "<string>",
      "error_code": "<string>",
      "created_at": "<string>",
      "user_id": "<string>",
      "end_user_id": "<string>",
      "provider_latency_ms": 123,
      "platform_latency_ms": 123,
      "ttft_ms": 123,
      "error_category": "<string>",
      "error_message": "<string>",
      "failure_stage": "<string>",
      "images_generated": 123,
      "model_type": "<string>",
      "is_byok": true,
      "byok_key_id": "<string>",
      "byok_key_label": "<string>",
      "provider": "<string>",
      "fallback_triggered": true,
      "platform_fee_usd": "<string>",
      "image_tokens": 123,
      "member_name": "<string>",
      "member_email": "<string>",
      "attempt_no": 123,
      "is_retry_attempt": true,
      "routing_fallback": true,
      "model_requested": "<string>"
    }
  ],
  "rejection": {
    "request_id": "<string>",
    "created_at": "<string>",
    "key_id": "<string>",
    "model": "<string>",
    "failure_stage": "<string>",
    "error_code": "<string>",
    "status_code": 123,
    "path": "<string>",
    "latency_ms": 123
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Usage

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.

GET

usage

requests

{request_id}

Get Request

curl --request GET \
  --url https://api.meshapi.ai/v1/usage/requests/{request_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.meshapi.ai/v1/usage/requests/{request_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.meshapi.ai/v1/usage/requests/{request_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.meshapi.ai/v1/usage/requests/{request_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.meshapi.ai/v1/usage/requests/{request_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "request_id": "<string>",
  "outcome": "<string>",
  "retention_days": 123,
  "ambiguous": false,
  "event": {
    "id": "<string>",
    "key_id": "<string>",
    "key_label": "<string>",
    "request_id": "<string>",
    "model": "<string>",
    "model_name": "<string>",
    "model_provider": "<string>",
    "stream": true,
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123,
    "cost_usd": "<string>",
    "latency_ms": 123,
    "tokens_per_second": 123,
    "status": "<string>",
    "error_code": "<string>",
    "created_at": "<string>",
    "user_id": "<string>",
    "end_user_id": "<string>",
    "provider_latency_ms": 123,
    "platform_latency_ms": 123,
    "ttft_ms": 123,
    "error_category": "<string>",
    "error_message": "<string>",
    "failure_stage": "<string>",
    "images_generated": 123,
    "model_type": "<string>",
    "is_byok": true,
    "byok_key_id": "<string>",
    "byok_key_label": "<string>",
    "provider": "<string>",
    "fallback_triggered": true,
    "platform_fee_usd": "<string>",
    "image_tokens": 123,
    "member_name": "<string>",
    "member_email": "<string>",
    "attempt_no": 123,
    "is_retry_attempt": true,
    "routing_fallback": true,
    "model_requested": "<string>"
  },
  "attempts": [
    {
      "id": "<string>",
      "key_id": "<string>",
      "key_label": "<string>",
      "request_id": "<string>",
      "model": "<string>",
      "model_name": "<string>",
      "model_provider": "<string>",
      "stream": true,
      "prompt_tokens": 123,
      "completion_tokens": 123,
      "total_tokens": 123,
      "cost_usd": "<string>",
      "latency_ms": 123,
      "tokens_per_second": 123,
      "status": "<string>",
      "error_code": "<string>",
      "created_at": "<string>",
      "user_id": "<string>",
      "end_user_id": "<string>",
      "provider_latency_ms": 123,
      "platform_latency_ms": 123,
      "ttft_ms": 123,
      "error_category": "<string>",
      "error_message": "<string>",
      "failure_stage": "<string>",
      "images_generated": 123,
      "model_type": "<string>",
      "is_byok": true,
      "byok_key_id": "<string>",
      "byok_key_label": "<string>",
      "provider": "<string>",
      "fallback_triggered": true,
      "platform_fee_usd": "<string>",
      "image_tokens": 123,
      "member_name": "<string>",
      "member_email": "<string>",
      "attempt_no": 123,
      "is_retry_attempt": true,
      "routing_fallback": true,
      "model_requested": "<string>"
    }
  ],
  "attempt_count": 0,
  "retry_count": 0,
  "related_events": [
    {
      "id": "<string>",
      "key_id": "<string>",
      "key_label": "<string>",
      "request_id": "<string>",
      "model": "<string>",
      "model_name": "<string>",
      "model_provider": "<string>",
      "stream": true,
      "prompt_tokens": 123,
      "completion_tokens": 123,
      "total_tokens": 123,
      "cost_usd": "<string>",
      "latency_ms": 123,
      "tokens_per_second": 123,
      "status": "<string>",
      "error_code": "<string>",
      "created_at": "<string>",
      "user_id": "<string>",
      "end_user_id": "<string>",
      "provider_latency_ms": 123,
      "platform_latency_ms": 123,
      "ttft_ms": 123,
      "error_category": "<string>",
      "error_message": "<string>",
      "failure_stage": "<string>",
      "images_generated": 123,
      "model_type": "<string>",
      "is_byok": true,
      "byok_key_id": "<string>",
      "byok_key_label": "<string>",
      "provider": "<string>",
      "fallback_triggered": true,
      "platform_fee_usd": "<string>",
      "image_tokens": 123,
      "member_name": "<string>",
      "member_email": "<string>",
      "attempt_no": 123,
      "is_retry_attempt": true,
      "routing_fallback": true,
      "model_requested": "<string>"
    }
  ],
  "matches": [
    {
      "id": "<string>",
      "key_id": "<string>",
      "key_label": "<string>",
      "request_id": "<string>",
      "model": "<string>",
      "model_name": "<string>",
      "model_provider": "<string>",
      "stream": true,
      "prompt_tokens": 123,
      "completion_tokens": 123,
      "total_tokens": 123,
      "cost_usd": "<string>",
      "latency_ms": 123,
      "tokens_per_second": 123,
      "status": "<string>",
      "error_code": "<string>",
      "created_at": "<string>",
      "user_id": "<string>",
      "end_user_id": "<string>",
      "provider_latency_ms": 123,
      "platform_latency_ms": 123,
      "ttft_ms": 123,
      "error_category": "<string>",
      "error_message": "<string>",
      "failure_stage": "<string>",
      "images_generated": 123,
      "model_type": "<string>",
      "is_byok": true,
      "byok_key_id": "<string>",
      "byok_key_label": "<string>",
      "provider": "<string>",
      "fallback_triggered": true,
      "platform_fee_usd": "<string>",
      "image_tokens": 123,
      "member_name": "<string>",
      "member_email": "<string>",
      "attempt_no": 123,
      "is_retry_attempt": true,
      "routing_fallback": true,
      "model_requested": "<string>"
    }
  ],
  "rejection": {
    "request_id": "<string>",
    "created_at": "<string>",
    "key_id": "<string>",
    "model": "<string>",
    "failure_stage": "<string>",
    "error_code": "<string>",
    "status_code": 123,
    "path": "<string>",
    "latency_ms": 123
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Enter your MeshAPI key (rsk_...) or, for the admin-keys endpoints, a dashboard session token — sent as Authorization: Bearer <token>.

Headers

X-Mesh-Version

enum<string>

default:2026-08

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.

Available options:

2026-08

Path Parameters

request_id

string

required

Response

Successful Response

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.

request_id

string

required

outcome

string

required

'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

integer

required

How far back this endpoint can resolve a request id.

ambiguous

boolean

default:false

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.

event

UsageEventOut · object | null

The request itself: the attempt that served it.

Show child attributes

attempts

UsageEventOut · object[]

Every attempt including retried failures, oldest first.

Show child attributes

attempt_count

integer

default:0

retry_count

integer

default:0

attempt_count - 1.

Other billed rows this request produced (e.g. a memory embedding).

Show child attributes

matches

UsageEventOut · object[]

Populated only when ambiguous.

Show child attributes

rejection

RejectionOut · object | null

Populated only when outcome is 'rejected'.

Show child attributes

Overview

Endpoints

Get Request

Authorizations

Headers

Path Parameters

Response