Usage & Monitoring API

The usage endpoints expose usage, spend, rate-limit, and balance data programmatically. Each authenticates with an rsk_ API key, so anything you can see in the console you can also pull from your own code.

What	Endpoint
Requests / tokens / spend aggregates	`POST /v1/usage`
Per-request history	`POST /v1/usage/events`
One request by its `X-Request-Id`	`GET /v1/usage/requests/{request_id}`
Live RPM / RPD / TPM vs limits	`GET /v1/usage/rate-limits`
Remaining credit balance (with reserved breakdown)	`GET /v1/balance`

Full request/response schemas and an interactive explorer are in the API Reference tab. This page is the guide. For the usage block on each completion response, see Usage Object.

CSV export (GET /v1/usage/events/export) is dashboard-only — it authenticates the signed-in session and is not callable with an API key. Forecasting / usage prediction is not part of this API yet.

Authentication & scoping

Credential	Header	Scope
API key	`Authorization: Bearer rsk_<key>`	That key’s own usage. `key_id` / `team_id` / member filters are ignored. Spend trend is the exception: it returns org-wide spend.

On POST /v1/usage, POST /v1/usage/events, and the request lookups, an API key reads only the usage of the key it authenticated with. The server sets that scope, and request parameters cannot widen it. The dashboard’s own views are org-scoped instead, which is why the org / team / member scopes appear in these schemas. GET /v1/usage/spend-trend does not narrow to the key. Any member’s rsk_ key gets the whole org’s spend, or one team’s spend with team_id (the key’s owner must belong to that team). org_id is required on POST /v1/usage, POST /v1/usage/events, and GET /v1/usage/spend-trend. Leave it out and the call fails with 422. The usage and events endpoints ignore its value for an API key, so any placeholder works. Spend trend needs the key’s real organization ID; read it as org_id from GET /v1/keys, which takes an admin key ($MESH_ADMIN_KEY), not an rsk_ key.

Usage summary — `POST /v1/usage`

Aggregate requests, tokens, and spend, plus a per-model breakdown. Filters are a JSON body (the array filters are more natural as a body than query params).

curl https://api.meshapi.ai/v1/usage \
  -H "Authorization: Bearer rsk_<key>" \
  -H "Content-Type: application/json" \
  -d '{"org_id": "<ORG_ID>", "since": "2026-07-01", "until": "2026-07-14", "limit": 10}'

Body field	Notes
`org_id`	Required. For an API key any value works, because the scope comes from the key itself.
`since` / `until`	ISO 8601. Bare dates cover the whole day.
`model`	`string[]` — filter by model ids.
`status`	`string[]`, e.g. `success`, `error`.
`model_type`	`string[]` — filter by modality, e.g. `image`, `video`.
`service_tier`	`string[]` — the tier that served, e.g. `flex`.
`failure_stage`	`string[]` — failures in one pipeline stage, e.g. `upstream_stream`.
`routing`	`string[]` — requests routing did not serve on the first attempt: `retried`, `provider_fallback`, `model_fallback`. Unknown values are a `422`.
`end_user_id`	Narrow to one end-user identifier.
`request_id`	Narrow to a single request.
`tags` / `tag_key`	Rows carrying all of these request tags; group the summary by one tag key.
`key_id` / `team_id` / `member_user_id`	Dashboard scopes, ignored for API keys.
`limit` / `offset`	Paginate the `by_model` breakdown (`limit` ≤ 200).

{
  "total_requests": 1284,
  "successful_requests": 1270,
  "error_requests": 14,
  "prompt_tokens": 482913,
  "completion_tokens": 197233,
  "total_tokens": 680146,
  "total_cost_usd": "12.4832100",
  "by_model_total": 3,
  "by_model": [
    {
      "model": "openai/gpt-4o-mini",
      "requests": 900,
      "total_tokens": 420000,
      "cost_usd": "6.1200000"
    }
  ]
}

Totals span the full range; by_model is one page (by_model_total is the full distinct-model count). Monetary values are strings to preserve decimal precision.

Per-request history — `POST /v1/usage/events`

Paginated list of individual requests, newest first. Same filters as the summary, plus limit (≤ 200) / offset.

curl https://api.meshapi.ai/v1/usage/events \
  -H "Authorization: Bearer rsk_<key>" \
  -H "Content-Type: application/json" \
  -d '{"org_id": "<ORG_ID>", "status": ["success"], "limit": 20}'

{
  "events": [
    {
      "id": "0190a1c0-0000-7000-8000-00000000e1e1",
      "request_id": "req_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "model": "openai/gpt-4o-mini",
      "prompt_tokens": 128,
      "completion_tokens": 64,
      "total_tokens": 192,
      "cost_usd": "0.0000480",
      "latency_ms": 812,
      "status": "success",
      "created_at": "2026-07-14T10:15:30+00:00"
    }
  ],
  "total": 1284,
  "limit": 50,
  "offset": 0
}

Retried “waste” attempts are collapsed — each request appears once (the served attempt). A cross-provider routing fallback surfaces as the boolean routing_fallback.

One request — `GET /v1/usage/requests/{request_id}`

Look up a single request by the id returned in its X-Request-Id response header: the model and provider that served it, status, latency, tokens, cost, and every attempt made. A request refused before any model was called (rate limit, spend cap, empty balance, model access) has no usage row and comes back with outcome: "rejected".

curl https://api.meshapi.ai/v1/usage/requests/<REQUEST_ID> \
  -H "Authorization: Bearer rsk_<key>"

Ids resolve for 90 days — see How far back data goes, which is the one place on this page where a window applies. An older id, or one made by a different key, returns 404. Requests to /v1/chat/compare and /v1/batches are not resolvable here. Use GET /v1/batches/{batch_id} for a batch.

Per-attempt timeline — `GET /v1/usage/events/{event_id}/attempts`

When a request was retried or rerouted, this returns every attempt that shares its request_id — the served row plus each retried row, oldest first. It is how you see every model that was tried behind one collapsed event.

curl https://api.meshapi.ai/v1/usage/events/<EVENT_ID>/attempts \
  -H "Authorization: Bearer rsk_<key>"

Authorization mirrors the events list: an API-key caller sees only events made by that key. The same scrubbing applies — no admin fields — and a failed attempt’s error_message may name the provider that answered it.

Spend trend — `GET /v1/usage/spend-trend`

Historical spend for the key’s whole org, not only the key, bucketed by granularity. The response adds a trailing 3-bucket moving average and the window’s total.

curl "https://api.meshapi.ai/v1/usage/spend-trend?org_id=<ORG_ID>&granularity=monthly" \
  -H "Authorization: Bearer rsk_<key>"

Parameter	Notes
`org_id`	Required. The key’s own org. Any other value is a `403`.
`team_id`	Optional. Narrow to one team the key’s owner belongs to.
`granularity`	`hourly` (last 24 hours, hourly buckets), `weekly` (last 12 weeks, weekly buckets), or `monthly` (last 30 days, daily buckets; the default).
`force_refresh`	Bypass the cached result.

Rate limits — `GET /v1/usage/rate-limits`

Live RPM / RPD / TPM counters vs. the effective limits (always fresh, never cached). For an API-key caller only the key scope is populated.

curl https://api.meshapi.ai/v1/usage/rate-limits \
  -H "Authorization: Bearer rsk_<key>"

{
  "as_of": "2026-07-14T10:20:00+00:00",
  "org": null,
  "team": null,
  "member": null,
  "key": {
    "rpm": { "current": 42, "limit": 60, "is_default_limit": false, "pct": 70.0, "resets_in_seconds": 37 },
    "rpd": { "current": 5120, "limit": 10000, "is_default_limit": false, "pct": 51.2, "resets_in_seconds": 49200 },
    "tpm": { "current": 18000, "limit": 20000000, "is_default_limit": true, "pct": 0.09, "resets_in_seconds": 37 }
  }
}

Each metric carries current, the effective limit, pct (0–100), and resets_in_seconds. A limit the key does not explicitly set is shown as the system default with is_default_limit: true (the TPM default is display-only — keys with no explicit tpm_limit are not TPM-throttled). Use pct to draw a usage bar and warn as it nears 100. The dashboard sees the org / team / member scopes instead of the single key scope.

Balance — `GET /v1/balance`

Current credit balance, plus how much is reserved by in-flight operations (realtime sessions, async background jobs, video generation) and therefore not spendable.

curl https://api.meshapi.ai/v1/balance \
  -H "Authorization: Bearer rsk_<key>"

{
  "balance_usd": "42.5000000",
  "reserved_usd": "15.0000000",
  "available_usd": "27.5000000",
  "reserved_breakdown": [
    { "kind": "realtime", "reserved_usd": "5.0000000" },
    { "kind": "video", "reserved_usd": "10.0000000" }
  ],
  "updated_at": "2026-07-14T10:15:30+00:00"
}

With an org context the org owner’s balance is returned — all org members share one billing pool; a personal key with no org gets its own balance. available_usd = max(0, balance_usd − reserved_usd); reserved_breakdown lists only the categories currently holding funds and sums to reserved_usd.

How far back data goes

Not every endpoint on this page reaches back the same distance, and the difference is deliberate: usage and spend are billing records, while prompts and completions are your content.

What	How far back
Usage aggregates — `POST /v1/usage`	No limit. Your full account history
Per-request history — `POST /v1/usage/events`	No limit
Spend trend — `GET /v1/usage/spend-trend`	No limit
Balance — `GET /v1/balance`	Current, with its own ledger history
One request by id — `GET /v1/usage/requests/{request_id}`	Up to 90 days, then `404`
Request and response bodies on that lookup	Up to 90 days
Refused requests — `POST /v1/usage/rejections`	Up to 90 days
Audit log	365 days
Webhook delivery history	30 days

Spend and usage history has no cutoff. You can pull last quarter or last year from POST /v1/usage and POST /v1/usage/events — requests, tokens, cost, model, status and latency, per request, for as far back as your account goes. If you are reconciling an invoice or charting a year of spend, these are the endpoints to use. Two things are capped at 90 days: looking up one request by its id, and refused requests. Past that the lookup returns 404 whether or not the request existed, and request and response bodies are not available at all. Refused requests — the ones rejected before reaching a model — have the same cap, so they age out of POST /v1/usage/rejections while the served requests around them stay in POST /v1/usage/events indefinitely. 90 days is a ceiling, not a floor. It is the furthest these two will reach, and today they reach less: the request log holds data from 6 August 2026 onward, because it was re-partitioned by month with 30 days of history carried over and the older partition retired. Anything before that is archived and not available through the API. The reachable window grows day by day until it meets the 90-day cap in early November 2026, after which it is a rolling 90 days. Treat a 404 or an absent body as “not available”, never as “this request did not happen”. The cap on the lookup is not an accident of storage — it is why the response carries retention_days:

{
  "request_id": "req_...",
  "outcome": "success",
  "retention_days": 90
}

Read that field rather than hard-coding 90, so a change to the window does not silently break your integration.

Only the bodies and the single-request lookup stop being available. The per-request metadata — model, tokens, cost, status, latency, your request_tags — stays available from POST /v1/usage/events for as long as your account exists, so it needs no archiving on your side. If you need the request and response bodies beyond the window, capture them inside it.These windows describe what this API will return, not a deletion schedule, and they are not a data-retention commitment. Bodies are also returned only where the key that served the request had body logging enabled.

Notes

Money is always a decimal string (never a float).
Caching: API-key reads are computed fresh; the dashboard’s org-scoped summary/events reads are cached ~60s (?refresh=true bypasses). Rate-limits and balance are never cached.
Errors use the standard envelope — 401 (bad credential), 403 (not an org member), 429 (rate limited).

Introduction

Accounts & Access

Core Inference

Retrieval & Search

Multimodal

Operations

Mesh Code

Mesh CLI

Platform

Reference

Usage & Monitoring API

Authentication & scoping

Usage summary — `POST /v1/usage`

Per-request history — `POST /v1/usage/events`

One request — `GET /v1/usage/requests/{request_id}`

Per-attempt timeline — `GET /v1/usage/events/{event_id}/attempts`

Spend trend — `GET /v1/usage/spend-trend`

Rate limits — `GET /v1/usage/rate-limits`

Balance — `GET /v1/balance`

How far back data goes

Notes

​Authentication & scoping

​Usage summary — POST /v1/usage

​Per-request history — POST /v1/usage/events

​One request — GET /v1/usage/requests/{request_id}

​Per-attempt timeline — GET /v1/usage/events/{event_id}/attempts

​Spend trend — GET /v1/usage/spend-trend

​Rate limits — GET /v1/usage/rate-limits

​Balance — GET /v1/balance

​How far back data goes

​Notes

Authentication & scoping

Usage summary — `POST /v1/usage`

Per-request history — `POST /v1/usage/events`

One request — `GET /v1/usage/requests/{request_id}`

Per-attempt timeline — `GET /v1/usage/events/{event_id}/attempts`

Spend trend — `GET /v1/usage/spend-trend`

Rate limits — `GET /v1/usage/rate-limits`

Balance — `GET /v1/balance`

How far back data goes

Notes