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

# Rate limits

> How the DarknetSearch API limits requests — how to read your usage and limits, and how to handle a 429.

The API caps how many requests you can make to each endpoint. You can see your limits and how much you've used at any time, so you can pace an integration and never be surprised by a `429`.

<Info>
  Two limits apply to every call — an **account-wide cap** across all endpoints, and a **per-endpoint** limit — each over a fixed window. Check either with **`get_usage_limits`** or the **`X-RateLimit-*` headers** on every response.
</Info>

### How the limits stack

Every request passes through **two** limits, and it has to clear both:

* **Account-wide cap — the ultimate bucket.** Every call, to any endpoint, counts against one shared cap: **25 / second** and **100,000 / month**. Run either down and *every* endpoint returns `429` until the window resets.
* **Per-endpoint limits — the individual buckets.** On top of the cap, each endpoint has its own allowance (for example, `domain_quick_search` at 100 / day). This only affects that endpoint.

```mermaid theme={"dark"}
flowchart TB
    REQ["Every API request"] --> CAP
    subgraph CAP["Account-wide cap · 25 / second · 100,000 / month"]
        E1["domain_quick_search<br/>100 / day"]
        E2["accounts_database_search<br/>10,000 / day"]
        E3["telegram-search-create<br/>100 / day"]
        E4["…one bucket per endpoint"]
    end
    CAP --> CHECK{"Room in the endpoint bucket<br/>AND the account-wide cap?"}
    CHECK -->|Yes| OK["Request runs"]
    CHECK -->|No| ERR["429 Too Many Requests"]
```

Every successful call draws down **both** its endpoint bucket and the account-wide cap — so you can hit a `429` either by hammering one endpoint or by high total volume across all of them, whichever empties first. Windows are calendar-aligned in **UTC** (a daily limit resets at the end of the UTC day, a monthly one at month end), and **failed calls are refunded** — only successful requests count.

### Check your usage

Call **`GET /service/get_usage_limits/`** to see your limits and consumption — per endpoint and account-wide. It reads the same live counters the rate limiter enforces, so `used` and `remaining` are exact.

```bash theme={"dark"}
curl https://client-api.leak.center/api/service/get_usage_limits/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json theme={"dark"}
{
  "total": [
    { "period": "1 Day", "limit": 50000, "used": 1240, "remaining": 48760, "reset_seconds": 27239 }
  ],
  "services": [
    {
      "feature": "Leaked Credentials",
      "service_name": "Email Quick Search",
      "service_slug": "email_quick_search",
      "limits": [
        { "period": "1 Day", "limit": 100, "used": 13, "remaining": 87, "reset_seconds": 27239 }
      ]
    }
  ]
}
```

* **`services`** — one block per endpoint you can call. Each `limits` entry is one window: `limit`, `used`, `remaining`, and `reset_seconds` (seconds until it resets). `period` is the window label (`1 Day`, `1 Hour`, `1 Month`).
* **`total`** — your account-wide limits across all endpoints, when any are set. Returned only when you don't filter.

Narrow the response with query parameters:

| Parameter      | Effect                                                                                                            |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `service_slug` | Only endpoints whose slug matches (partial, case-insensitive) — e.g. `?service_slug=quick_search`. Omits `total`. |
| `feature`      | Only endpoints under a feature — e.g. `?feature=Leaked`. Omits `total`.                                           |
| `org_id`       | For MSSP / system accounts: read a specific managed organization's usage.                                         |

→ [`get_usage_limits` in the API reference](https://client-api.leak.center/scalar-docs/#tag/general-endpoints/GET/api/service/get_usage_limits/)

#### On every response, too

You don't have to poll `get_usage_limits` to stay aware of your budget — every rate-limited response also carries it in headers:

| Header                  | Meaning                                            |
| ----------------------- | -------------------------------------------------- |
| `X-RateLimit-Limit`     | Your allowance for that endpoint's current window. |
| `X-RateLimit-Remaining` | How many requests you have left.                   |
| `X-RateLimit-Reset`     | Seconds until the window resets.                   |

```http theme={"dark"}
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 27239
```

Use the headers for lightweight per-call tracking; call `get_usage_limits` when you want the full picture up front — for example, before a large batch job.

<Note>
  **Live Search** adds a capacity endpoint on top of this — [`live_search_capacity`](/api/guides/live-search) — reporting remaining real-time searches for the hour, day, and month plus current queue depth, because it draws on a limited pool of live crawler accounts.
</Note>

### When you exceed a limit

A request over the limit returns **`429 Too Many Requests`** before it runs, and tells you exactly how long to wait:

```http theme={"dark"}
HTTP/1.1 429 Too Many Requests
Retry-After: 27239
```

```json theme={"dark"}
{
  "message": "Rate limit exceeded",
  "retry_after_seconds": 27239,
  "limit": 100,
  "remaining": 0,
  "reset_at": "2026-07-06T23:59:59+00:00"
}
```

* **`Retry-After`** (header) and **`retry_after_seconds`** (body) both give the seconds to wait before retrying. For a daily window that can be hours — queue the work rather than blocking on it.
* A `429` **doesn't cost you** — rejected requests aren't counted against your budget.
* Failed requests are refunded too. If a call returns a non-2xx (say a `400` or a `502`), the slot it took is credited back — so only successful work counts against your limit.

### Limits by endpoint

Every endpoint has its own limit. See **[Rate limits by endpoint](/api/guides/rate-limits-reference)** for the exact limit on every endpoint, or call [`get_usage_limits`](#check-your-usage) for your account's live figures.

### Best practices

<Steps>
  <Step title="Read your usage, don't guess">
    Watch `X-RateLimit-Remaining` (or poll `get_usage_limits`) and ease off before it reaches zero. That's cheaper than recovering from a `429`.
  </Step>

  <Step title="Respect Retry-After on a 429">
    When you do hit a `429`, wait `retry_after_seconds` before retrying — don't hammer the endpoint. For daily windows that value can be hours, so queue the work.
  </Step>

  <Step title="Spread out batch jobs">
    Enriching a large list? Pace requests across the window instead of firing them all at once — and where one exists, prefer a bulk/database endpoint (10,000/day) over per-item quick searches (100/day).
  </Step>

  <Step title="Cache what you can">
    Results don't change second to second. Cache responses and reuse them rather than re-querying the same term.
  </Step>
</Steps>

<Info>
  **Rate limits are separate from credits.** API requests are governed by the rate limits on this page. *Credits* are an organization-level measure, surfaced as `used_credits` in your [organization info](/api/guides/setup) — they track dashboard usage, not API rate limiting.
</Info>