Rate limits

How the API rate is measured, per team and in cost units, and how to adapt to it.

Updated on October 3, 2026

The rate belongs to the team, not to the token: every token of a team shares the same envelope, set by your plan, per minute and per day.

Cost units

Each operation costs a number of units, published in the reference: a simple read costs 1, an aggregated report more. Each response carries its cost (X-Request-Cost) and the state of the windows:

RateLimit-Policy and RateLimit (IETF format);
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset for the minute window.

curl -i "https://api.nessflow.com/v1/usage" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN"

GET /v1/usage also returns the consumption of each window and your plan quotas.

When the limit is reached

The API answers 429 rate_limited, with the Retry-After header and, in the body, window (minute or day), retry_after and upgrade_to, the plan that would raise the limit. Wait Retry-After seconds before retrying.

Spend less

A request refused for exceeding the limit (429), or answering 304, costs nothing.
Send the ETag you received in If-None-Match: an unchanged resource answers 304, for free.
Prefer webhooks to polling.