Skip to main content
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. 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.

​
Rate Limit Headers

Every authenticated API response reports all three per-organization windows in their own namespace: 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:
The per-organization hourly quota returns:
The per-organization burst limiters (per-minute shown here; per-second is analogous) return:
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 429s even when your hourly quota has room, and exhausting the hourly bucket causes 429s 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?

Contact Us

Contact our team to discuss custom rate limits for enterprise needs

​
Need Help?