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

# Rate limits

> Per-key per-action budgets, plus the credit meter.

Repo enforces two independent limits:

1. **Rate limit** — short-window requests-per-minute, per `(api_key, action)` pair. Prevents abuse and accidental loops.
2. **Credit budget** — monthly answer-call cap tied to your billing plan. Counts toward billing.

## Rate limit

Default: **60 requests per minute** per `(api_key, action)` combination. Configurable per-deployment via `API_RATE_LIMIT_PER_MIN`.

A request that exceeds the limit returns `429` with:

```http theme={null}
Retry-After: <seconds until reset>
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: <ISO 8601 timestamp>
```

```json theme={null}
{
  "error": "Rate limit exceeded",
  "action": "search",
  "limit": 60,
  "retryAfterSeconds": 47,
  "resetAt": "2026-05-30T20:15:00Z"
}
```

Window: rolling 1 minute. Counts are tracked in Postgres so the limit holds across multiple API instances.

### Per-action accounting

Each action has its own bucket. A key doing 50 `search` and 50 `context` calls in the same minute is fine (each is under 60); the limit kicks in at the 61st call to *either* action.

### Recommended client behavior

* Back off with exponential jitter on `429`. Don't tight-loop retry.
* Cache aggressively — Repo's retrieval is deterministic for the same query within a sync window (\~15 min).
* Consider one key per agent rather than sharing — gives each agent its own 60/min budget.

## Credit budget

The credit meter is the billing dimension. 1 credit = 1 retrieval call (`/v1/search`, `/v1/context`, `/v1/ask`).

| Tier           | Monthly credits | Over-cap behavior                              |
| -------------- | --------------- | ---------------------------------------------- |
| **Builder**    | 5,000           | **Hard block** — returns `429 quota_exceeded`  |
| **Studio**     | 25,000          | **Overage allowed** — \$0.015 per extra answer |
| **Scale**      | 100,000         | **Overage allowed** — \$0.015 per extra answer |
| **Enterprise** | Custom          | Per contract                                   |

Credits reset at the start of each billing period (matches your Stripe subscription's `current_period_start`).

### What counts as a credit

* `/v1/search` — 1 credit
* `/v1/context` — 1 credit
* `/v1/ask` — 1 credit
* `/v1/console/ask` — 1 credit (same enforcement; see [#3 in the security fixes](/billing))

These do **not** count:

* `/v1/sources` (list connectors)
* `/v1/sync-runs` (queue or list)
* `/v1/api-keys` (mint or list)
* `/v1/memory-canvas` (graph view)
* `/v1/audit-events` (audit log read)
* `/v1/ingest` (custom document push)
* Console-only routes that don't trigger retrieval

### Checking your usage

```bash theme={null}
curl https://api.userepo.com/v1/console/billing \
  -H "Authorization: Bearer <supabase-token>"
```

Returns the current period's `creditsUsed`, `creditsIncluded`, and `creditsRemaining`. The console's **Billing** tab renders the same data with a usage meter.

### Overage reporting

For Studio/Scale, overage credits are reported to Stripe in real time via the Meter Events API. Your monthly invoice includes a line item for `(actual_credits - included_credits) × $0.015`.

## Combined rule

A request that passes the rate limit can still fail the credit budget, and vice versa. Both checks must succeed for retrieval to run.