Skip to main content
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

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.
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: 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.
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.
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.
The billing dashboard lives at 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:
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.
  • 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