One balance, one tariff.
Every organization has a single balance in US dollars. The Playground, the API and the MCP server all draw from it at the same tariff, and you only pay for pages that succeed.
The tariff
| part | price |
|---|---|
| Successful page | US$0.0005 |
| Search | billed as one page |
| Provider cost (proxies, browsers, search and model providers) | measured cost × 5 |
| Failed page, or a page that fails your validators | US$0 |
Provider cost is passed through only when it is measured; an unknown cost is not estimated or charged. Each result and job reports what it cost you in customerChargeUsd, and GET /api/v1/pricing returns the live tariff.
Balance and packs
New organizations start with a US$1 welcome balance. Top up at /app/billing — checkout opens inside the page, and the balance is credited after the payment is confirmed. Each step up the ladder adds 10 points of bonus balance; there is no subscription.
| pack | balance credited | bonus |
|---|---|---|
US$8 | US$8 | — |
US$50 | US$55 | +10% |
US$200 | US$240 | +20% |
US$1,000 | US$1,300 | +30% |
Only owners and admins can buy. Refunds and disputes take the credited amount back off the balance.
Reservations
Before work starts, the server reserves the most the request could cost, and settles it down to the measured charge when the job ends; the difference returns to the balance. The ceiling is:
ceiling = US$0.0005 × requested pages + maxCostUsd × 5maxCostUsd is the request's provider budget. On scrape, crawl, map and batch you may pass maxCustomerCostUsd to set your own ceiling — it must be at least the one above. When you omit it, the server reserves exactly that ceiling. If the balance cannot cover it, the request answers 402 before anything runs.
Ceilings at the defaults:
| request | maxCostUsd | reserved |
|---|---|---|
| scrape | 0.02 | ≈ US$0.10 |
| search | 0.1 | ≈ US$0.50 |
| crawl, 20 pages | 0.15 | ≈ US$0.76 |
| map, 100 pages | 0.15 | ≈ US$0.80 |
| batch, 10 pages | 0.15 | ≈ US$0.76 |
| research | 0.5 (default) | ≈ US$2.50 |
| research | 0.05 (minimum) | ≈ US$0.25 |
| research | 5 (maximum) | ≈ US$25.00 |
Research on a small balance
Scrape, search, crawl, map and batch at their default size fit the US$1 welcome balance. Research reserves about US$2.50 at its default budget, so it needs a top-up first — or pass a smaller maxCostUsd (from 0.05) for a shorter report. Reports and pages settle at what the run actually spent, typically well under the ceiling.
Errors
Every error has the same envelope. Branch on error.code, not on the message.
{ "error": { "code": "insufficient_scraping_balance" } }| status | code | what to do |
|---|---|---|
| 400 | invalid_request | Fix the body; it failed validation (see the reference for bounds). |
| 400 | customer_cap_below_required_ceiling | Raise maxCustomerCostUsd, lower maxCostUsd or pages — or omit the cap. |
| 401 | unauthorized | Send a valid key that has the operation's scope. |
| 402 | insufficient_scraping_balance | Top up at /app/billing, or lower the request's ceiling. |
| 402 | customer_budget_exceeded | The job reached its ceiling; remaining pages were not charged. |
| 403 | organization_required | Finish onboarding: the account has no organization. |
| 403 | forbidden · invalid_origin | Owner/admin role needed, or a cross-origin session call. |
| 404 | not_found | The job, key or session is not in this organization. |
| 409 | idempotency_conflict | Same Idempotency-Key with a different body. |
| 429 | monthly_quota_exceeded | The plan's monthly jobs or pages are used up. |
| 429 | plan_page_limit | Too many pages in one job for the plan. |
| 429 | scraping_capacity_reached | 20 active jobs per organization; wait for one to finish. |
| 503 | worker_unavailable · billing_not_configured · … | Not configured here or temporarily down; retry with backoff. |
Authentication
Every /api/v1 call is made by an organization API key in the Authorization header. Keys are scoped, shown once, and revocable by the organization's owners and admins.
MCP
Sparkcrawl speaks the Model Context Protocol. Point an MCP client at the remote server with your API key, or run the stdio package locally — the tools call the same /api/v1 with the same scopes, quotas and balance.