# Rate limits

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

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.

```bash
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.