---
updatedAt: 2026-10-09T13:45:25.000Z
agentTools:
  projectIndex: https://developers.leadboxer.com/llms.txt
---

# Rate Limiting

To protect the platform and ensure fair usage across clients, API requests are subject to per-minute rate limits. When a client exceeds the limit for an endpoint, further requests to that endpoint are rejected until the window resets.

## How Limits Are Applied

* Limits are counted **per account**. All API keys that belong to the same account share the same limit.
* Limits are counted **per endpoint**. Requests to one endpoint do not use up the limit of another. For endpoints with an ID in the path (for example `/v1/leads/{leadId}`), each ID is counted separately.
* Each limit uses a **fixed one-minute window** that starts with the first request. When the window ends, the counter resets.
* There are **no daily or monthly request quotas**. Longer-term usage is governed by credits, see [Credit Usage & Cost Model](https://developers.leadboxer.com/docs/credit-usage-cost-model).

***

## Limits per Endpoint

| Endpoint                                                          | Requests per minute |
| ----------------------------------------------------------------- | ------------------- |
| `GET /v1/ip-lookup`                                               | 100                 |
| `GET /v1/domain-lookup`                                           | 100                 |
| `GET`/`POST /v1/email-lookup` (shared limit)                      | 30                  |
| `GET /v1/leads`                                                   | 30                  |
| `GET /v1/leads/{leadId}`                                          | 60                  |
| `GET /v1/leads/export`                                            | 30                  |
| `GET /v1/leads/sessions`                                          | 20                  |
| `GET /v1/leads/events`                                            | 30                  |
| `PUT /v1/management/lead-tags`, `PUT /v1/management/assign-leads` | 30                  |
| `GET`, `POST`, `DELETE /v1/user-datasets`                         | 30                  |
| `POST /v1/datasets`                                               | 5                   |
| `DELETE /v1/datasets/{datasetId}`                                 | 5                   |
| `PUT /v1/datasets/{datasetId}/name`                               | 60                  |
| `PUT /v1/datasets/{datasetId}/form-tracking`                      | 60                  |
| `GET /v1/segments`                                                | 60                  |
| `POST /v1/segments`                                               | 5                   |
| `PUT /v1/segments/{segmentId}`                                    | 30                  |
| `PUT /v1/segments/user`                                           | 30                  |
| `DELETE /v1/segments/{segmentId}`                                 | 30                  |
| `GET`, `PUT`, `DELETE /v1/segment/preference`                     | 60                  |
| `POST /v1/users`                                                  | 10                  |
| `GET /v1/users/{userId}/invite/resend`                            | 10                  |
| `PUT /v1/users/{userId}/name`                                     | 100                 |
| `DELETE /v1/users/{userId}`                                       | 10                  |
| `GET /v1/users/datasets`                                          | 60                  |
| `POST /v1/management/ctd/validate`                                | 10                  |
| `POST /v1/management/ctd/add`                                     | 1                   |
| `GET /v1/management/ctd/{datasetId}`                              | 30                  |
| `PUT /v1/management/ctd/update`                                   | 30                  |
| `DELETE /v1/management/ctd/{datasetId}`                           | 1                   |

Endpoints not listed here currently have no per-minute limit. Limits may change, so clients should always read the rate-limit headers rather than hard-code these numbers.

***

## Rate Limit Response Headers

Responses from rate-limited endpoints include headers that describe the current rate-limit state for your account on that endpoint.

| Header                      | Description                                                                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **`X-RateLimit-Limit`**     | The maximum number of requests allowed for this endpoint within the one-minute window.                                           |
| **`X-RateLimit-Remaining`** | The number of requests remaining in the current window.                                                                          |
| **`X-RateLimit-Reset`**     | The time the current window resets, as a Unix timestamp in seconds.                                                              |
| **`Retry-After`**           | The number of seconds the client must wait before retrying the request. **Returned only when the rate limit has been exceeded.** |

***

## Example Headers When Limit Is Reached

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1766565255
Retry-After: 46
```

### Interpretation

* This endpoint allows **100 requests per minute** for your account
* All requests for the current window have been used
* The window resets at Unix time **1766565255**, which is **46 seconds** from now
* Any additional requests to this endpoint before the reset will be rejected

***

## HTTP 429 – Too Many Requests

When the rate limit is exceeded, the API returns:

```
HTTP/1.1 429 Too Many Requests
```

### Response Characteristics

* The request is **not processed** and does not consume credits
* The response includes a `Retry-After` header indicating when it is safe to retry
* The response body describes the limit, see [Rate Limit Exceeded](https://developers.leadboxer.com/docs/rate-limit-exceeded)

***

## Client Retry Guidelines

Clients are expected to implement responsible retry behavior.

### Required Behavior

* **Do not retry immediately** after receiving a `429` response
* Respect the `Retry-After` header value
* Resume requests only after the specified delay

### Recommended Best Practices

* Implement **automatic retry with backoff**
* When `X-RateLimit-Remaining` reaches `0`, pause requests to that endpoint until the `X-RateLimit-Reset` time
* Avoid parallel retries from several API keys of the same account, since they share one limit

***

## Example Retry Logic (Pseudo-Flow)

1. Send request
2. If response is **200–299** → continue
3. If response is **429**:

   * Read `Retry-After`
   * Sleep for the specified duration
   * Retry the request