# Rate limits

The Product API is rate-limited per organization and per endpoint class. Ceilings depend on your subscription plan and can be raised by upgrading.

Every Product API endpoint enforces a request-per-minute ceiling. Limits are scoped by organization and by endpoint class — hot endpoints (scroll, search, aggregations) have their own budgets so a heavy reporting job cannot starve an interactive dashboard.

## Ceilings follow your plan

Base limits are tied to the subscription plan your organization is on. Upgrading the plan raises every ceiling across the board, typically by a generous multiplier per tier:

| Plan   | Profile                                                                             |
| ------ | ----------------------------------------------------------------------------------- |
| **S**  | Starter workloads: a few interactive users, light sync.                             |
| **M**  | Growing integrations: mixed read/write, several daily sync jobs.                    |
| **L**  | Production scale: continuous sync, real-time dashboards, larger audiences.          |
| **XL** | High-volume platforms: multi-region reporting, heavy aggregations, bulk operations. |

If you are hitting `429`s regularly and your workload genuinely needs the headroom, the path forward is to **upgrade the plan** — see the **Billing** section of the [dashboard](https://dashboard.instasent.com) or talk to your account manager. For one-off spikes (backfills, seasonal traffic, audits) open a ticket with the expected peak rate and we will raise the ceiling on your organization for the duration.

## Reading the headers

Every response includes three headers with the current window state. Log them in production — they are the cheapest way to spot a client that is about to hit the wall.

```
X-RateLimit-Limit      600
X-RateLimit-Remaining  587
X-RateLimit-Reset      1893452400
```

| Header                  | Meaning                                                                        |
| ----------------------- | ------------------------------------------------------------------------------ |
| `X-RateLimit-Limit`     | Total requests allowed in the current window, for the plan and endpoint class. |
| `X-RateLimit-Remaining` | Requests left before the window tightens.                                      |
| `X-RateLimit-Reset`     | Unix timestamp when the counter resets.                                        |

## Designing for the ceiling

A few patterns keep a Product API integration comfortably below the line:

- **Scroll, don't paginate-and-forget.** The `/audience/scroll` and `/event/scroll` endpoints are built for large traverses — they hold a cursor, cost one hit per page and are generous on page size.
- **Cache project-level specs.** Attribute and event specs barely change; call `/specs/*` once per deploy, not per request.
- **Batch writes.** Ingest endpoints accept up to 100 items per call. A batched write counts as one hit.
- **Separate credentials per workload.** An interactive dashboard and a nightly backfill should not share a token — they share the same ceiling, which hides problems.

## When you hit the limit

Requests that exceed the window return **`429 Too Many Requests`**. The body is empty; the `X-RateLimit-Reset` header tells you when to retry.

> **Tip**: Back off exponentially rather than retrying in a tight loop. A client that hammers a 429 response keeps the window full and never recovers — waiting until `X-RateLimit-Reset` resolves the situation cleanly.

## What's next

- **[Errors](/product-api/errors)** — every status code you might receive, including `429`.
- **[API Reference](/product-api/reference)** — per-endpoint documentation.