Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nusomi.com/llms.txt

Use this file to discover all available pages before exploring further.

Nusomi enforces rate limits at two layers: per API key (to protect against runaway scripts) and per workspace (to protect aggregate cost).

​
Default limits

SurfacePer keyPer workspace
POST /v1/sessions (create)30 / s200 / s
POST /v1/sessions/:id/events (emit)1000 / s5000 / s
POST /v1/sessions/:id/frames (upload)200 / s1000 / s
GET reads (sessions, events, frames)200 / s2000 / s
Streaming /events/stream50 concurrent500 concurrent
POST /v1/exports5 / minute30 / minute
POST /v1/replays (live sandbox)10 / minute50 / minute
These are the defaults for a new workspace. Limits scale with workspace tier and are visible at any time: 
curl https://api.nusomi.com/v1/limits \
  -H "Authorization: Bearer $NUSOMI_API_KEY"

​
Headers

Every response includes: 
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1715091600
X-Scope: per_key
When you hit a limit: 
HTTP/1.1 429 Too Many Requests
Retry-After: 4
X-RateLimit-Reset: 1715091604
Retry-After is in seconds.

​
Burst behavior

Limits are token-bucket. The bucket size is 2× the per-second rate, and refills continuously. So a 200/s limit lets you burst 400 requests then drain — useful for catch-up after a network hiccup.

​
Request batching

A few endpoints accept batches to reduce QPS pressure:
EndpointMax batch
POST /v1/sessions/:id/events100 events
POST /v1/sessions/:id/frames50 frames
{ "events": [ { ... }, { ... } ] }
A batch counts as one request against the rate limit. Each item still counts toward quota.

​
Quotas vs. rate limits

Rate limits are about request rate. Quotas are about absolute volume per billing period. Hitting a quota returns quota_exceeded (also 429). Quota state: 
curl https://api.nusomi.com/v1/quota \
  -H "Authorization: Bearer $NUSOMI_API_KEY"

{
  "period_start": "2026-05-01T00:00:00Z",
  "period_end":   "2026-06-01T00:00:00Z",
  "captured_minutes": 18_412,
  "captured_minutes_limit": 25_000,
  "exported_rows": 3_120_500,
  "exported_rows_limit": null
}
null means unlimited (typical on enterprise tiers).

​
Asking for a higher limit

Email support@nusomi.com with your workspace ID, the surface you’re hitting limits on, and a rough QPS estimate. Same-day turnaround for read-heavy increases.