> For the complete documentation index, see [llms.txt](https://docs.revenium.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.revenium.io/integrations/rate-limits.md).

# Rate Limits

Revenium applies three rate limits so that one caller cannot degrade the platform for everyone: a **per-API-key ceiling at the edge**, applied before a request reaches the application, **per-account buckets inside the application**, and an **error-pattern limit per API key and team**, also inside the application. All answer `429 Too Many Requests`. This page describes each limit, how to tell which one refused a request, and what to do about it.

Limits are set to protect the platform and are raised on request; see [Need a higher limit?](#need-a-higher-limit) below.

*Last updated 29 October 2026.*

## Edge limit: per API key

Every request under `https://api.revenium.ai/profitstream/` that carries an `x-api-key` header is counted per key at the edge. Metering ingest (`/meter/v2/**` and `/v2/otlp/**`) is outside this scope and does not consume the allowance.

| Scope                                                                | Limit                    | Window              | When refused                 |
| -------------------------------------------------------------------- | ------------------------ | ------------------- | ---------------------------- |
| All REST API endpoints under `https://api.revenium.ai/profitstream/` | 300 requests per API key | trailing 60 seconds | `429` with `Retry-After: 60` |

* The limit is **per API key, not per account**. Two keys under one account each get their own 300 requests per minute.
* Requests that carry no `x-api-key` header, such as the Revenium web app on a user session, are not counted at this layer.
* Nothing is banned. A key over the limit keeps receiving `429` only while its request count over the trailing 60 seconds stays above 300; once it drops back under, requests are served again with no reset on your side. Detection and release can each lag by up to about 30 seconds.
* Metering ingest (`/meter/v2/**` and `/v2/otlp/**`) is not enforced at the edge today. It is governed by the application limits below.

An edge refusal carries a `Retry-After` header and this body, and **no** `X-RateLimit-*` headers:

```json
{
  "error": "rate_limited",
  "message": "This API key exceeded 300 requests in 60 seconds on the Revenium API. Retry after the Retry-After header; contact support@revenium.io to raise the limit."
}
```

## Application limits: per-account buckets

Revenium applies generous rate limits inside the application to keep usage predictable for agents and integrations. Limits are scoped per account and grouped into three buckets, each with its own ceiling and observable response headers.

### Buckets and limits

Every authenticated request is mapped to one of three buckets based on the path. Each bucket has its own request-per-second limit.

| Bucket      | Paths                                                                                                                                                                      | Limit         |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `metering`  | `/meter/v2/**` (REST metering: AI completions, events, tool, API) and `/v2/otlp/**` (OTLP signals)                                                                         | 1,000 req/sec |
| `analytics` | AI Metrics, AI Traces, billing analytics, chart and cost-attribution reads                                                                                                 | 100 req/sec   |
| `platform`  | All other `/profitstream/v2/api/**` and `/v2/sdk/**` endpoints (CRUD on subscriptions, tenants, sources, integrations, alerts, models, anomalies, plus SDK auth endpoints) | 50 req/sec    |

Bucket limits are per account, not per API key. If your integration uses multiple keys under the same account, they share the bucket budget.

Metering ingest additionally carries a **per-key** limit of 100 requests per second for each API key, reported with the same headers and `metering` bucket value as the account bucket. A single key cannot exceed 100 requests per second on `/meter/v2/**` or `/v2/otlp/**` even when the account bucket has budget left.

### Response headers

Four headers appear on every authenticated response that resolves to a bucket, regardless of status code (`2xx`, `4xx`, `5xx`, `204`).

| Header                  | Meaning                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window for this bucket                          |
| `X-RateLimit-Remaining` | Requests remaining in the current window. Reaches `0` at the limit, never goes negative |
| `X-RateLimit-Reset`     | Unix epoch (seconds) when the current window resets                                     |
| `X-RateLimit-Bucket`    | Which bucket this request mapped to: `metering`, `analytics`, or `platform`             |

Use `Remaining` to throttle preemptively. Use `Reset` to schedule your next batch. Use `Bucket` so a metering call does not back off because a platform call was busy.

Limits reset each second. Use `X-RateLimit-Reset` to see exactly when.

### When you hit the limit

A request that exceeds the bucket budget returns `429 Too Many Requests` with two additional headers and a JSON body.

**Additional headers:**

| Header                       | Meaning                                                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `Retry-After`                | Seconds to wait before retrying. Integer, always present                                                                             |
| `X-RateLimit-Limited-Reason` | Why the limit fired. Values: `bucket-rate` (bucket exhaustion) or `error-pattern` (repeated `401`, `403`, `404`, or `405` responses) |

**Response body:**

```json
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for bucket metering. Retry after 1 second.",
    "bucket": "metering",
    "doc_url": "https://docs.revenium.io/integrations/rate-limits"
  }
}
```

The `bucket` field is present when `Limited-Reason` is `bucket-rate`. For `error-pattern`, the body still has `type`, `code`, `message`, and `doc_url`, but no `bucket`.

## Error-pattern limit: per API key and team

Beyond the per-account buckets, Revenium temporarily blocks a key that keeps sending failed requests. This protects the API from misconfigured integrations that repeat broken calls. This limit is not per account. Failed requests are counted per API key and per team the request asks for: the key's own team, another team, or no team. The team is the `teamId` query value, or the team in the path of the Claude Code budget, experience-policy and league calls. Every other call counts as no team.

Only responses `401`, `403`, `404`, and `405` count. Other errors, such as `400` or `422`, never count.

When a key has 20 counted failures within 5 minutes for a team scope, calls from that key to that team scope are blocked. The first block lasts 30 seconds. Each repeat doubles the block, up to 1 hour. Repeats are remembered for 24 hours.

A blocked call returns `429` with a `Retry-After` header and `X-RateLimit-Limited-Reason: error-pattern`. `Retry-After` is the time left in the block.

Fix the underlying request (credentials, method, path, or IDs). If a wrong team id caused the block, correcting it clears the block at once, because the corrected calls are counted under the key's own team. Any other block lasts until `Retry-After` runs out.

## Which layer refused you

| You see                                                                                                                | Layer                                     |
| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `X-RateLimit-Bucket` and `X-RateLimit-Limited-Reason` headers, JSON body with `type: rate_limit_error` and a `doc_url` | Application bucket or error-pattern limit |
| `Retry-After` header only, JSON body with `error: rate_limited`                                                        | Edge per-key limit                        |

Honor `Retry-After` from any limit. The edge value is always `60`; the application value is the seconds left in the current window or block.

## Recommended client behavior

1. **Read the headers.** Treat `X-RateLimit-Remaining` and `X-RateLimit-Reset` as authoritative. If `Remaining` is low, slow down before you hit `0`.
2. **Honor `Retry-After`.** On `429`, wait at least that many seconds before retrying. Do not retry sooner.
3. **Use exponential backoff with jitter on repeat 429s.** Start at the `Retry-After` value and add randomized jitter to avoid thundering-herd retries with other clients in your account.
4. **Differentiate by `Limited-Reason`:**
   * `bucket-rate`: you are sending too fast. Throttle by `Remaining`.
   * `error-pattern`: your key is sending failing requests. Fix the request, not the rate.
5. **Separate metering from platform calls.** The metering bucket has 20x the platform budget. A busy `platform` flow should not slow down `metering`.

## Need a higher limit?

If you have a use case that needs sustained higher throughput, on a specific bucket or for a specific API key, [contact support](mailto:support@revenium.io) with the key name and the request rate you need so we can review the integration and raise the limit.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.revenium.io/integrations/rate-limits.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
