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

# Rate Limits

> Understanding API rate limits and best practices

The Promptwatch API enforces several layers of rate limiting to keep the platform stable and fair across customers. One layer is per-IP (anti-abuse); the rest are per-organization and sized by your plan.

## Per-IP Limit

All HTTP requests are rate-limited to **1,000 requests per minute** per IP address. This limit applies uniformly to every endpoint, is independent of authentication, and exists purely to absorb abuse. It is reported under its own `X-RateLimit-IP-*` headers so it never collides with your plan limits.

## Per-Organization Limits

Authenticated requests (REST `/api/v1`, REST `/api/v2`, and the MCP server at `/mcp`) share **per-organization limits** across three windows. Every API key tied to your organization draws from the same buckets — there is no separate counter per key, and the MCP and REST surfaces share them too.

| Plan       | Per second | Per minute (burst) | Per hour (quota) |
| ---------- | ---------: | -----------------: | ---------------: |
| Explore    |         10 |                150 |              100 |
| Solo       |         10 |                150 |              500 |
| Startup    |         10 |                150 |            2,000 |
| Business   |         23 |                334 |           10,000 |
| Enterprise |         30 |                834 |           50,000 |

Agency plans inherit the same numbers from their hourly quota (Kickoff = Solo, Growth = Startup, Scale = Business).

* **Hourly quota** is your total plan volume. The window is a fixed UTC hour and resets at the top of every hour (`HH:00:00 UTC`).
* **Per-minute and per-second burst limits** are derived from your hourly quota (`minute = min(834, max(150, ceil(hourly / 60) x 2))`, `second = min(30, max(5, ceil(minute / 15)))`). They smooth bursts so a short spike can't drain your hourly quota in a few seconds. Each resets at the top of the next UTC minute / second.

If you need higher limits, [contact us](mailto:team@promptwatch.com).

## Rate Limit Headers

Every authenticated API response reports all three per-organization windows in their own namespace:

| Header                                               | Description                                                                          |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `X-RateLimit-Limit` / `-Remaining` / `-Reset`        | Hourly plan quota: limit, remaining, and the Unix timestamp (seconds) when it resets |
| `X-RateLimit-Minute-Limit` / `-Remaining` / `-Reset` | Per-minute burst window                                                              |
| `X-RateLimit-Second-Limit` / `-Remaining` / `-Reset` | Per-second burst window                                                              |
| `Retry-After`                                        | Seconds to wait before retrying (only set on `429` responses)                        |

The per-IP headers (`X-RateLimit-IP-*`) are only present on the `429` response returned when the IP limit is exceeded — they are suppressed on normal responses to avoid ambiguity with your plan headers.

## 429 Response

When you exceed any limit you receive a `429 Too Many Requests` response.

The per-IP limiter returns:

```json theme={null}
{
  "code": "RATE_LIMITED",
  "message": "Too many requests, please slow down",
  "statusCode": 429
}
```

The per-organization hourly quota returns:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "You've hit your hourly API request limit of 500 requests. Try again in 30 minutes, or upgrade your plan to increase your limit.",
  "retryAfter": 1800,
  "limit": 500,
  "remaining": 0
}
```

The per-organization burst limiters (per-minute shown here; per-second is analogous) return:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "You're sending requests too quickly. You can make up to 150 requests per minute. Try again in 1 minute.",
  "retryAfter": 42,
  "limit": 150,
  "remaining": 0
}
```

`Retry-After` reflects the window that tripped: up to 1 second for the per-second guard, seconds-to-next-minute for the per-minute burst, and seconds-to-next-hour for the hourly quota. Use it (or the matching `X-RateLimit-*-Reset`) to decide when to retry rather than backing off arbitrarily.

## Best Practices

### Cache Responses

Cache static or rarely-changing data:

* **Models**: Cache for 24 hours
* **Monitors**: Cache for 1 hour
* **Analytics**: Cache based on date range

### Spread Traffic

All windows are shared across MCP and REST and across every API key in your organization. The per-second and per-minute burst caps mean sudden spikes get `429`s even when your hourly quota has room, and exhausting the hourly bucket causes `429`s for the rest of the hour. Pace recurring jobs (analytics syncs, backfills) across the window and keep concurrency modest rather than firing everything at once.

## Fair Use Policy

Please use the API responsibly:

* Don't make unnecessary requests
* Implement caching where appropriate
* Use batch operations when available
* Respect rate limit headers

Abuse of the API may result in temporary or permanent suspension of access.

## Increasing Limits

Need higher limits for your use case?

<Card title="Contact Us" icon="envelope" href="mailto:team@promptwatch.com">
  Contact our team to discuss custom rate limits for enterprise needs
</Card>

## Need Help?

* **Email**: [team@promptwatch.com](mailto:team@promptwatch.com)
* **Website**: [promptwatch.com](https://promptwatch.com)