Usage & Monitoring API

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

Full request/response schemas and an interactive explorer are in the API Reference. This page is the guide.

Authentication & scoping

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.

$
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}'

1
{
2
  "total_requests": 1284,
3
  "successful_requests": 1270,
4
  "error_requests": 14,
5
  "prompt_tokens": 482913,
6
  "completion_tokens": 197233,
7
  "total_tokens": 680146,
8
  "total_cost_usd": "12.4832100",
9
  "by_model_total": 3,
10
  "by_model": [
11
    {
12
      "model": "openai/gpt-4o-mini",
13
      "requests": 900,
14
      "total_tokens": 420000,
15
      "cost_usd": "6.1200000"
16
    }
17
  ]
18
}

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}'

1
{
2
  "events": [
3
    {
4
      "id": "0190a1c0-0000-7000-8000-00000000e1e1",
5
      "request_id": "req_01ARZ3NDEKTSV4RRFFQ69G5FAV",
6
      "model": "openai/gpt-4o-mini",
7
      "prompt_tokens": 128,
8
      "completion_tokens": 64,
9
      "total_tokens": 192,
10
      "cost_usd": "0.0000480",
11
      "latency_ms": 812,
12
      "status": "success",
13
      "created_at": "2026-07-14T10:15:30+00:00"
14
    }
15
  ],
16
  "total": 1284,
17
  "limit": 50,
18
  "offset": 0
19
}

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.

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

Live RPM / RPD / TPM counters vs. the effective limits (always fresh, never cached). Only the key scope is populated; org / team / member are always null.

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

1
{
2
  "as_of": "2026-07-14T10:20:00+00:00",
3
  "org": null,
4
  "team": null,
5
  "member": null,
6
  "key": {
7
    "rpm": { "current": 42, "limit": 60, "is_default_limit": false, "pct": 70.0, "resets_in_seconds": 37 },
8
    "rpd": { "current": 5120, "limit": 10000, "is_default_limit": false, "pct": 51.2, "resets_in_seconds": 49200 },
9
    "tpm": { "current": 18000, "limit": 1000000, "is_default_limit": true, "pct": 1.8, "resets_in_seconds": 37 }
10
  }
11
}

Each metric carries current, the effective limit, pct (0–100), and resets_in_seconds. RPM and TPM are per-minute windows; RPD resets at midnight UTC. A limit the key does not explicitly set is shown as the system default with is_default_limit: true. Use pct to draw a usage bar and warn as it nears 100.

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>"

1
{
2
  "balance_usd": "42.5000000",
3
  "reserved_usd": "15.0000000",
4
  "available_usd": "27.5000000",
5
  "reserved_breakdown": [
6
    { "kind": "realtime", "reserved_usd": "5.0000000" },
7
    { "kind": "video", "reserved_usd": "10.0000000" }
8
  ],
9
  "updated_at": "2026-07-14T10:15:30+00:00"
10
}

If your key belongs to an organization, the organization’s shared balance is returned — all members draw from 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: API-key reads are computed fresh (never cached).
• Errors use the standard envelope — 401 (bad credential), 422 (bad UUID / invalid filter), 429 (rate limited).