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

# Limits

> Request quota, Watch entitlements, and how your plan changes both.

Two different things bound your usage: **credits** (what a call costs — see [Credits](/credits))
and the limits on this page (how often you may call, and how many Watches you may run).
Your plan sets both.

## Plan entitlements

| Plan    | Requests / min | Active Watches | Min Watch interval | Monthly credits |
| ------- | -------------- | -------------- | ------------------ | --------------- |
| Free    | 60             | 1              | 3600s              | 0               |
| Starter | 350            | 5              | 300s               | 650,000         |
| Growth  | 700            | 15             | 60s                | 2,000,000       |
| Pro     | 1,200          | 50             | 30s                | 5,500,000       |

Credit packs top up your balance but never change the limits above — those move only with
the plan.

## Request quota

`/v1/*` is limited per **Account** (not per API key) in a rolling 60-second window, at the
requests-per-minute figure for your plan. Exceeding it returns **429** with
`code: "TOO_MANY_REQUESTS"`; see [Errors — Rate limits](/errors#rate-limits) for the
envelope and the `RateLimit-*` / `Retry-After` headers.

Because the quota is per Account, extra API keys do not buy extra throughput.

<h2 id="watch-entitlements">
  Watch entitlements
</h2>

Watch limits are enforced at **two** levels, and the stricter one wins.

### Minimum interval

```
effective minimum = max(plan minimum, source minimum)
```

Source minimums are 15s for Vinted and 60s for X, Reddit, and Youtube ([Watches](/watches#per-source-limits)).
Because the plan floor is never below 30s, **Vinted's 15s Source floor is not reachable on any
current plan** — the fastest Vinted watch is 30s, on Pro. On Free the effective minimum is
3600s, so `refresh_interval_seconds: 15` is rejected with **400** `VALIDATION` even though the
Source itself allows it.

| Plan    | Vinted | X / Reddit / Youtube |
| ------- | ------ | -------------------- |
| Free    | 3600s  | 3600s                |
| Starter | 300s   | 300s                 |
| Growth  | 60s    | 60s                  |
| Pro     | 30s    | 60s                  |

The maximum is always **3600s**, on every plan and Source.

### Active Watch cap

Creating a Watch checks the plan cap **account-wide across all Sources** first, then the
per-Source cap (Vinted 50, X/Reddit/Youtube 20). On Free the account-wide cap of 1 is
what you hit — the per-Source numbers only become reachable on Pro.

Both rejections are **400** `VALIDATION`.

## Downgrades pause what no longer fits

Moving to a lower plan does not delete Watches. Any Watch that now breaks the new
entitlements — polling faster than the new minimum, or beyond the new cap — is paused with
`pausedReason: plan_entitlement`. Oldest Watches are kept first; the newest ones are
paused.

Nothing resumes automatically. After upgrading again, call
`POST /v1/{source}/watches/{id}/resume` per Watch. Resume re-checks the cap and interval,
so it fails while the Watch still exceeds them.

<Note>
  A Watch paused by support (`pausedReason: admin_paused`) cannot be resumed with the API —
  it returns **409** `CONFLICT`.
</Note>

## Next steps

* [Credits](/credits) — what each call costs
* [Watches](/watches) — lifecycle and per-Source behaviour
* [Errors](/errors) — status codes and the error envelope