Usage & Monitoring API

The usage endpoints expose usage, spend, rate-limit, and balance data programmatically. Each accepts either a dashboard session token (JWT) or 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`
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 the API Reference tab. This page is the guide.

Spend-trend and CSV export are part of the dashboard (session-token) surface — they take an org_id and are 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>`	Only that key’s own usage. `org_id` / `team_id` / member filters are ignored.
Session token	`Authorization: Bearer <jwt>`	Org-scoped (requires `org_id`); owners/admins see the whole org, members see only their own usage.

An API key can only ever read the usage of the key it authenticated with — the scope is derived server-side and cannot be widened by request parameters.

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 '{"since": "2026-07-01", "until": "2026-07-14", "limit": 10}'

Body field	Notes
`org_id`	Required for session-token callers; ignored for API keys.
`since` / `until`	ISO 8601. Bare dates cover the whole day.
`model`	`string[]` — filter by model ids.
`status`	`string[]`, e.g. `success`, `error`.
`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 '{"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). Which upstream provider served a request is never exposed; a cross-provider routing fallback surfaces only as the boolean routing_fallback.

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 provider names, no admin fields.

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

Historical spend bucketed by granularity, plus 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=day" \
  -H "Authorization: Bearer <jwt>"

Parameter	Notes
`org_id`	Required. The org to report on.
`team_id`	Optional — narrow to one team.
`granularity`	Bucket size, e.g. `day`.
`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": 1000000, "is_default_limit": true, "pct": 1.8, "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 today). Use pct to draw a usage bar and warn as it nears 100. Session-token callers instead get the org / team / member scopes (and must pass org_id).

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.

Notes

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

Introduction

Accounts & Access

Core Inference

Retrieval & Search

Multimodal

Operations

Mesh CLI

Platform

Reference

Usage & Monitoring API

Authentication & scoping

Usage summary — `POST /v1/usage`

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

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`

Notes

​Authentication & scoping

​Usage summary — POST /v1/usage

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

​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

​Notes

Authentication & scoping

Usage summary — `POST /v1/usage`

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

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`

Notes