# API rate limits and 429 responses (https://snitchfeed.com/docs/api/rate-limits)



## Overview [#overview]

Every v1 endpoint is limited in two ways, **per organization** (not per key or token):

1. **Rate:** requests per 60-second window, counted separately for each endpoint group below.
2. **Concurrency:** **at most 2 in-flight requests** at a time across **all** v1 endpoints combined.

Going over either limit returns `429 Too Many Requests` with error code `rate_limited`, an `error.retryAfter` value in seconds and a matching `Retry-After` header.

### How requests are counted [#how-requests-are-counted]

Requests pass through authentication, the scope check, the concurrency check and then the rate limiter, in that order.

* A request rejected for authentication, scope or concurrency never reaches the rate limiter and does not use a rate limit token.
* Every request that reaches the rate limiter uses one token, whatever happens next. Validation errors, out-of-credit errors and upstream failures all count.
* Each window lasts 60 seconds from the first request counted in it. When it ends, the full limit is available again. `X-RateLimit-Reset` tells you when that is.
* The concurrency cap counts requests that have started and not yet finished, including slow LinkedIn calls. A third overlapping request is rejected immediately; it does not wait in line. A request releases its slot when its response is sent, whether it succeeded or failed.

## `/v1/data/*` endpoints [#v1data-endpoints]

**20 requests per minute** for each search surface. X, LinkedIn and Hacker News each have their own independent counter:

| Surface     | Endpoints                                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| X           | `/v1/data/twitter/tweets/search`                                                                                                            |
| LinkedIn    | `/v1/data/linkedin/posts/search`, `/company/get`, `/posts/comments`, `/posts/reactions`, `/person/posts`, `/person/comments`, `/industries` |
| Hacker News | `/v1/data/hackernews/search`                                                                                                                |

A burst of LinkedIn requests does not affect your X or Hacker News allowance. All LinkedIn endpoints, including the free industries lookup, share one counter.

## Organization data endpoints [#organization-data-endpoints]

**60 requests per minute**, one counter shared by:

* `/v1/mentions` (including `PATCH /v1/mentions/{id}/state`)
* `/v1/listeners`
* `/v1/feeds`
* `/v1/organization/context`
* `/v1/organization/usage`

These endpoints read data already stored for your organization rather than calling an external platform, so they get a higher shared limit.

## Response headers [#response-headers]

| Header                    | When present                                                  | Meaning                                                                                               |
| ------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`       | Every response that passed the rate limiter, success or error | Requests allowed per window for the counter this request used (`20` for `/v1/data/*`, `60` otherwise) |
| `X-RateLimit-Remaining`   | Same                                                          | Requests left in the current window                                                                   |
| `X-RateLimit-Reset`       | Same                                                          | Unix timestamp (seconds) when the current window ends                                                 |
| `X-Concurrency-Limit`     | Every response that passed authentication and the scope check | Max in-flight requests per organization (currently `2`)                                               |
| `X-Concurrency-Remaining` | Concurrency `429` only                                        | Always `0`                                                                                            |
| `Retry-After`             | Every `429`                                                   | Seconds to wait before retrying                                                                       |

A `429` from the rate limiter does not carry the `X-RateLimit-*` headers; use `Retry-After`.

## Handling 429s [#handling-429s]

* Wait for `Retry-After` seconds before retrying the same request.
* Keep at most 2 requests in flight per organization. If several services share one organization, they share this cap.
* Watch `X-RateLimit-Remaining` and slow down before it reaches `0`.

## Need higher throughput? [#need-higher-throughput]

Contact [hello@snitchfeed.com](mailto:hello@snitchfeed.com) if your workload needs custom limits.

## Related [#related]

* [SnitchFeed API](/docs/api/introduction): endpoints and error codes
* [API credits](/docs/api/credits): what each search call costs
* [API authentication](/docs/api/authentication): keys and tokens