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

# Credits and Limits

> What each Peel operation costs, how rate limits work, and how to handle `429` and `budget_exceeded`.

Peel bills in credits. Every build and runtime call deducts a fixed amount per operation, and per-actor rate limits cap how quickly you can send them.

## Credit cost per operation

| Operation                                         | Credits | When it applies                                                                                                                                   |
| ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Build an API (`POST /v1/apis`)                    | `50`    | Per **successful** build. Failed builds are refunded automatically. Matched builds (`matched: true`) reuse an existing API and are never charged. |
| Revise an API (`POST /v1/apis/{api_id}/revise`)   | `25`    | Per queued revision, whether or not the revision ultimately succeeds.                                                                             |
| Rebuild an API (`POST /v1/apis/{api_id}/rebuild`) | `0`     | Rebuilds are not charged directly. Runtime calls against the rebuilt contract are charged at the tiers below.                                     |
| `http_replay` / `graphql_replay` call             | `5`     | The cheapest deterministic path: one forwarded request against a compiled surface.                                                                |
| `html_tls` call                                   | `7`     | Deterministic TLS fetch plus HTML extraction. Costs more than replay because the server parses the response HTML and runs selectors.              |
| `http_flow` call                                  | `9`     | Fixed multi-step request chain when one request is not enough.                                                                                    |
| Premium call                                      | `10`    | `session_required` endpoints, CSRF-protected flows, or endpoints that require a premium proxy.                                                    |
| Action call                                       | `15`    | `guided_action` endpoints, which are deterministic write or side-effect flows.                                                                    |

The runtime cost of a specific endpoint is surfaced in its detail record as `endpoints[].credit_cost`. Inspect it before calling if budget is tight.

Browser investigation can happen during builds, but hosted runtime calls do not launch browsers. If Peel hits an anti-bot or JavaScript-only wall at runtime, the call returns a structured rebuild-required error instead of charging for an uncontrolled browser execution.

<Info>
  Actual defaults can vary by deployment. The values above are the hosted Peel defaults. Your account's billing dashboard shows the active pricing for your account.
</Info>

## Rate limits

Rate limits are enforced per actor, either per API key or per OAuth session:

| Surface                                                             | Limit                     | What it gates                                                         |
| ------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------- |
| Build dispatch (`POST /v1/apis`, `revise`, `rebuild`)               | `20` requests per minute  | Starting new builds or queueing changes.                              |
| Endpoint execution (`POST /v1/apis/{api_id}/endpoints/{name}:call`) | `120` requests per minute | Runtime calls against published endpoints.                            |
| MCP JSON-RPC (`POST /mcp`)                                          | `60` requests per minute  | Any JSON-RPC method, including platform tools and runtime tool calls. |
| Auth endpoints                                                      | `30` requests per minute  | OAuth authorize, token, revoke, and related flows.                    |

There is also a global build queue with a hard cap on concurrent in-flight builds across all actors. When the queue is saturated, new builds get `429` with a `Retry-After` header even if your per-actor rate is below its limit.

<Info>
  Rebuild is free in credits, but it still counts against the 20/min build dispatch rate limit shared with `POST /v1/apis` and `revise`. Triggering rebuilds in a tight loop is the fastest way to hit `429` without spending credits.
</Info>

**Failure semantics differ between build and revise.** A failed `POST /v1/apis` automatically reverses its reservation, so you are not charged for a failed first build or a first build canceled before publication. A failed `revise`, by contrast, consumes its 25 credits even if the build ends in `failed`. When you are iterating on instructions, inspect the failure before sending another `revise`.

**Runtime calls are billed on outcome.** Successful and failed runtime calls both consume credits. A call that reached the target and failed to parse still paid for the transport. The only runtime exception is `budget_exceeded`, which is a pre-flight rejection and is never billed.

## `429` vs `budget_exceeded`

These two look similar but mean different things:

* **HTTP `429`** is a rate problem. You are asking Peel to do things too quickly. Back off, respect `Retry-After`, and retry. Your account still has credits.
* **Runtime `error_code: "budget_exceeded"`** with HTTP `402` is a balance problem. You are out of credits for this call. Top up credits or wait for the next billing cycle. No retry will help until the balance goes up.

If you see `429` and `budget_exceeded` interleaved, fix the balance first. A drained account will keep hitting `budget_exceeded` on every retry and waste rate-limit budget on errors.

## Topping up credits

Credits top up in two ways:

* **Monthly plan.** Starter and Pro plans include a monthly credit allowance that resets on your billing cycle.
* **One-off top-ups.** Through the billing dashboard, you can purchase additional credits on demand. These stack on top of plan credits and do not expire at the next cycle.

| Catalog item | Price         | Credits                   | Renewal                   |
| ------------ | ------------- | ------------------------- | ------------------------- |
| Starter plan | `$29 / month` | `1,250` monthly credits   | Resets each billing cycle |
| Pro plan     | `$79 / month` | `5,000` monthly credits   | Resets each billing cycle |
| Top-up 200   | `$12`         | `200` purchased credits   | One-time purchase         |
| Top-up 500   | `$29`         | `500` purchased credits   | One-time purchase         |
| Top-up 1500  | `$79`         | `1,500` purchased credits | One-time purchase         |

The billing dashboard lives at [peel.sh/settings/pricing](https://peel.sh/settings/pricing) once you are signed in.

## Checking your balance programmatically

Use `GET /account/credits` with your `X-API-Key` to read the current credit balance and plan state. The current credit balance is also surfaced on the auth-introspection response when you call any public endpoint while authenticated. Check your client's error body on `budget_exceeded` for the latest figure, or use the billing dashboard for the authoritative number.

The CLI wrapper for the same account route is:

```bash theme={null}
peel credits
peel credits --json
```

`peel credits` renders the same public credit state as `GET /account/credits`: balance, plan, monthly allocation, purchased and subscription buckets, used-credit totals, subscription status, unlimited status, auto-recharge settings, and period timestamps. Use `--json` when an agent or script needs the exact response shape.

## Related pages

* [Errors](/reference/errors) — the full `error_code` catalog, including `budget_exceeded`
* [Authentication](/getting-started/authentication) — where `X-API-Key` fits in the billing model
* [API updates](/features/api-updates) — when a rebuild is worth the cost