> 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 rate limits at two layers 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, and **per-account buckets inside the application**. Both answer `429 Too Many Requests`. This page describes each layer, 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 25 September 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 4xx 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 protection

Beyond per-bucket budgets, Revenium temporarily slows callers that produce sustained `4xx` errors. This protects accounts from runaway misconfigured integrations spamming the API with broken requests.

Sustained `4xx` over a short window triggers a temporary block. Each consecutive violation doubles the cooldown, capped at one hour. `Retry-After` reflects the remaining cooldown. `X-RateLimit-Limited-Reason` will be `error-pattern`.

Fix the underlying request (auth, missing fields, invalid IDs) and the cooldown clears on its own.

## 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 protection |
| `Retry-After` header only, JSON body with `error: rate_limited`                                                        | Edge per-key limit                             |

Honor `Retry-After` from either layer. The edge value is always `60`; the application value is the seconds left in the current window or cooldown.

## 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`: you are sending broken requests. Fix the request shape, 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.