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. |
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.
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.
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. |
429 with a Retry-After header even if your per-actor rate is below its limit.
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.
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 |
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:
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 — the full
error_code catalog, including budget_exceeded
- Authentication — where
X-API-Key fits in the billing model
- API updates — when a rebuild is worth the cost