> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lumos API Rate Limits

> How many requests the Lumos API at api.lumos.com accepts per organization, what a rate-limited response looks like, and how to back off.

This page covers the request limits Lumos enforces on its public API at `https://api.lumos.com`, the response you get when you exceed them, and how to retry. For authentication and token setup, see [Build and Extend with Lumos](/reference/overview).

## Current limits

| Window | Requests allowed |
| - | - |
| Any 1 second | 100 |
| Any 1 minute | 4,000 |

Both limits apply at the same time. A request that would exceed either one is rejected.

* **Counted per organization.** Every API token in your Lumos organization shares one count. Creating more tokens doesn't raise the limit.
* **Shared across endpoints.** Every endpoint draws from the same count. There are no separate per-endpoint limits.
* **Moving window.** Lumos counts the requests made in the last second and the last minute, not since a fixed reset time. A burst stays counted for the full window after it happens.
* **Subject to change.** Lumos can adjust these values. Read the rate limit headers on each response instead of hardcoding the numbers.

Requests that don't use a Lumos API token (prefixed `lsk_`) are counted per credential.

## Rate limit headers

Lumos returns these headers so your client can track its usage.

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | The number of requests allowed in the window being reported |
| `X-RateLimit-Remaining` | Requests left in that window |
| `X-RateLimit-Reset` | When the oldest request counted in that window stops counting, as a Unix timestamp in seconds (it can include a fraction of a second) |
| `Retry-After` | On a `429` response, the seconds to wait before sending the next request |

On successful responses, these headers describe the 1-second window, so they don't show how much of the per-minute limit you've used. On a `429` response, the headers describe the window you exceeded.

## When you exceed a limit

Lumos rejects the request with `429 Too Many Requests` and doesn't process it. The response body depends on the endpoint.

`/v1` endpoints return the standard error envelope, with `type` and `code` set to `rate_limited`.

```json theme={null}
{
  "error": {
    "detail": "Too many requests",
    "type": "rate_limited",
    "code": "rate_limited",
    "errors": []
  }
}
```

Other endpoints, such as `/appstore/apps`, return a single error string.

```json theme={null}
{
  "error": "Too many requests"
}
```

SCIM endpoints under `/scim/v2` return an error in the SCIM error schema (RFC 7644).

## How to back off

1. Stop sending requests when you receive a `429`.
2. Wait the number of seconds in the `Retry-After` header, then retry the request.
3. Pace long-running jobs to stay under 4,000 requests per minute. `X-RateLimit-Remaining` on successful responses only tracks the 1-second window.
4. If a response has no `Retry-After` header, retry with exponential backoff and random jitter.

Because the count is shared across your organization, scripts and tools run by different teams draw from the same limit. Spread large jobs, such as bulk exports, over time instead of running them in parallel.