Rate Limits & Credits

Credit system

Every API call consumes credits. Credits are deducted when a request completes successfully. Failed requests (4xx errors caused by bad input) are not charged. Your balance resets monthly, at the start of your billing cycle. Credits do not roll over — unused credits expire at the end of the cycle, on every plan including paid ones.

Per-surface credit costs

Surface	Credits per call	Notes
Fetch (no JS)	1	Static HTML fetch, direct/stealth access tier
Fetch (JS rendering)	5	`render_js: true`, direct/stealth access tier
Fetch + extract	2 or 5	Flat 5 if extraction runs through the LLM, flat 2 otherwise — independent of `render_js`
Fetch — residential proxy surcharge	+65	Added on top of the base Fetch price only when your request needs a residential proxy — typically hardened, anti-bot-defended targets. Paid plans only.
Crawl	2 per page crawled	Charged per page, not per job. Subject to the same proxy-tier surcharge as Fetch below
Map	2 per URL mapped	Same base price and surcharge behavior as Crawl (billed under the `crawl` surface)
Interact	3	Per interaction session. Not subject to the proxy-tier surcharge below
Interact — prompt mode	25	Per session, using `prompt` instead of `actions` (see Interact). Flat regardless of how many steps the task takes
Interact — prompt mode residential proxy surcharge	+65	Added on top of the base 25 when `proxy: "stealth"` (or the deprecated `use_proxy: true`) is set. Requires a paid plan. Flat per session, not per step
Search (no fetch)	15	Google SERP only. Requires a Starter plan or higher
Search + fetch results	15 + normal Fetch cost (1 or 5) per fetched result	Each result is fetched via the standard Fetch surface, not a flat +1. Requires a Starter plan or higher
Fast Search	15	Organic results only, no HTML capture. Requires a Starter plan or higher
YouTube search	10	Requires a Starter plan or higher
YouTube video details	10	Requires a Starter plan or higher
YouTube subtitles	10	Requires a Starter plan or higher
YouTube search crawl (async)	10 per page crawled	Requires a Starter plan or higher. Capped at 700 total results (`end_page * limit` must not exceed 700)
Google SERP search	15	Requires a Starter plan or higher
Amazon product / search	10	Requires a Starter plan or higher
Walmart search	10	Requires a Starter plan or higher
Booking.com search, property, reviews	15	Requires a Starter plan or higher
Agoda search, property, reviews	15	Requires a Starter plan or higher
Agoda search page 2+, reviews page 2+	25	Requires a Starter plan or higher
Airbnb search / listing	15	Requires a Starter plan or higher
Target product / search	15	Requires a Starter plan or higher
Reddit post / subreddit / user	15	Requires a Starter plan or higher
TikTok post	15	Requires a Starter plan or higher
Apple App Store app	15	Requires a Starter plan or higher
Bing search	15	Requires a Starter plan or higher
ChatGPT prompt	15	Requires a Starter plan or higher
Perplexity prompt	15	Requires a Starter plan or higher
Gemini prompt	15	Requires a Starter plan or higher

GET /v1/walmart/product was re-enabled on 2026-08-03, now backed primarily by our dedicated walmart_product target (with the generic browser-render path retained as a fallback) — this replaced the generic-only path that had been hitting frequent PerimeterX-related blocks on individual product pages.

Proxy tiers and the `proxy` parameter on Fetch, Crawl, and Map

Fetch, Crawl, and Map accept an optional proxy field that controls how far a request may escalate to get past anti-bot defenses:

`proxy`	What it does	Plans
`"basic"`	No proxy at all. If the target blocks it, the request fails with `proxy_required` and tells you to retry with `"auto"`. Billed at the base price.	All plans (the Free plan is always `"basic"`)
`"auto"`	The default on paid plans. Tries the cheap steps first and escalates to residential proxies only when needed, billed by the step that served the request.	Starter and higher
`"stealth"`	Skips straight to the strongest tier: a hardened browser behind a residential proxy. Use it when you already know a target needs it. The default `timeout_ms` is 20000 (10000 for the other modes) because this browser needs longer on heavy pages.	Starter and higher

When every access attempt only times out, the response is 504 timeout (not 502 target_blocked) and asks for a larger timeout_ms; a timeout_ms above your plan’s inline limit runs as an async job. use_proxy: true is a deprecated alias for proxy: "stealth". Sending use_proxy: true together with a different proxy value returns 400 invalid_request. On the Free plan, "auto" and "stealth" return 402 plan_upgrade_required. Every Fetch response reports what the request cost in usage, for example { "credits": 15, "base": 5, "surcharge": 10, "tier": "proxy_browser" }. The surcharge depends on the tier that actually served the request, not a flat rate:

`usage.tier`	What served it	Surcharge
`standard`	No proxy	+0
`proxy`	Browser-less request through a residential proxy (no JavaScript)	+4
`proxy_browser`	Real browser through a residential proxy	+10
`stealth`	Hardened browser through a residential proxy	+65
`cloudflare`	Cloudflare challenge solved with a real browser	+65

For Crawl and Map the surcharge applies per page/URL on top of the flat 2 credits: a 10-page crawl where 8 pages were served with no proxy and 2 needed the hardened browser bills 8 × 2 + 2 × (2 + 65) = 150 credits. Interact is billed at its flat per-session price and is not affected. Interact accepts the same proxy field, with two modes depending on how you call it:

Prompt mode (prompt): a single browser session with no ladder to escalate through, so it accepts "basic" (no proxy, the default) or "stealth" (residential proxy, +65 credits on top of the base 25). "auto" returns 400 invalid_request.
Actions mode (actions): "auto" (default on paid plans) uses the usual escalation ladder, "basic" never uses a proxy and skips the Cloudflare solver, and "stealth" goes straight to the hardened browser behind a residential proxy. A blocked "basic" request fails with proxy_required. Interact keeps its flat per-session price in every mode.

use_proxy: true also still works on Interact as an alias for proxy: "stealth".

Crawl and Map auto-promote to an async job on large requests

Crawl and Map normally run synchronously, fetching every page within the same HTTP request/response. If your request is large enough that it would plausibly exceed the tenant’s inline execution budget — max_pages/max_urls above the surface’s own default (25 for Crawl, 100 for Map), or an explicit timeout_ms above your plan’s inline timeout — the API automatically queues it as an async job instead of holding the connection open, and responds the same way POST /v1/jobs does:

{ "request_id": "...", "mode": "async", "status": "queued", "job_id": "...", "reason": "..." }

Poll GET /v1/jobs/{job_id} for the result, same as any other async job. Small/default requests are unaffected and stay synchronous — you can also opt into async explicitly at any size via POST /v1/jobs with { "kind": "crawl" | "map", "input": {...} }. If a request times out before the ladder would have reached its strongest tier, the 504 timeout error includes a hint suggesting proxy: "stealth" or a higher timeout_ms, unless the request already set proxy to "stealth" or "basic" or is on the Free plan (where the hint wouldn’t apply).

Plan limits

Plan	Monthly credits	Notes
Free	1,000	Resets monthly. No proxy access — see below.
Starter	25,000	Unlocks dedicated APIs (Amazon, Walmart, Booking.com, Agoda, YouTube, Airbnb, Target, Reddit, TikTok, Apple App Store, Bing, ChatGPT, Perplexity, Gemini), Fast Search, and Google SERP search.
Pro	100,000	Everything in Starter.
Scale	500,000	Everything in Pro, plus custom rate limits.
Enterprise	Custom	SLA + dedicated capacity

Credits do not roll over on any plan — unused credits expire at the end of the billing cycle.

Free plan does not include proxy access

The Free plan never routes requests through a datacenter or residential proxy — only direct HTTP and stealth-browser access. Most targets work fine without either, but sites with stronger anti-bot defenses may block Free-plan requests that would succeed on a paid plan. When this happens, the API returns free_plan_proxy_required (see Error Reference) instead of a generic block, so you know upgrading is the fix rather than retrying.

Dedicated APIs, Fast Search, and Google SERP search require a paid plan

Amazon, Walmart, Booking.com, Agoda, YouTube (search, video, subtitles, and search crawl), Airbnb, Target, Reddit, TikTok, Apple App Store, Bing, ChatGPT, Perplexity, Gemini, Fast Search, and Google SERP search all require a Starter plan or higher. Requesting any of these on an ineligible plan returns 402 plan_upgrade_required.

Quota errors

When your credit balance runs out, the API returns:

{
  "request_id": "...",
  "error": {
    "code": "credits_exhausted",
    "message": "Your plan's credit allowance has been exhausted. Buy a top-up or upgrade to continue."
  }
}

Code	Status	When
`credits_exhausted`	402	Balance is zero

Credits are a hard cap, not billed overage — requests are blocked once your plan’s included credits run out. Buy a top-up or upgrade to a higher plan to keep going.

Checking your usage

Use the usage field in every successful inline response to see how many credits that call consumed:

{
  "usage": { "credits": 5 }
}

Aggregate usage dashboards are available at scrapio.dev.

Getting Started

Guides

API Reference

Rate Limits & Credits

Credit system

Per-surface credit costs

Proxy tiers and the `proxy` parameter on Fetch, Crawl, and Map

Crawl and Map auto-promote to an async job on large requests

Plan limits

Free plan does not include proxy access

Dedicated APIs, Fast Search, and Google SERP search require a paid plan

Quota errors

Checking your usage

​Credit system

​Per-surface credit costs

​Proxy tiers and the proxy parameter on Fetch, Crawl, and Map

​Crawl and Map auto-promote to an async job on large requests

​Plan limits

​Free plan does not include proxy access

​Dedicated APIs, Fast Search, and Google SERP search require a paid plan

​Quota errors

​Checking your usage

Credit system

Per-surface credit costs

Proxy tiers and the `proxy` parameter on Fetch, Crawl, and Map

Crawl and Map auto-promote to an async job on large requests

Plan limits

Free plan does not include proxy access

Dedicated APIs, Fast Search, and Google SERP search require a paid plan

Quota errors

Checking your usage