Web scraping sandbox: test a scraping integration without spending credit
Use a web scraping sandbox to test your integration: test API keys, sandbox_scenario failures, async jobs, paused batches and signed webhooks, at no cost.
- Published
- Reading time
- 8 min read
- By
- ExtractHub team
- sandbox
- testing
- web scraping API
- webhooks
- CI
On this page
Most scraping integrations are tested in two ways: not at all, or against the live API with a real key. The first ships error handling nobody has run. The second costs credit on every test run, depends on a target site that may be down or changed today, and can never produce the failures you most need to test, like a paused batch or a request that turned into an async job.
A web scraping sandbox fixes both. ExtractHub test API keys run the exact same endpoints, validation and response shapes as live keys, but never fetch a page and never move credit. A sandbox_scenario parameter picks the outcome, so you can rehearse a failure, a slow answer, an async job or an empty balance on demand. This post shows how to set it up and what to test.
How the web scraping sandbox differs from live
Create a key on the API keys page and pick Test key (sandbox) as the key type. Test keys start with exth_test_; live keys with exth_. You send them exactly like a live key, as X-API-Key or Authorization: Bearer.
The same as live:
- Every extractor endpoint: realtime GET and POST extract, async jobs, the Batch API, and the status, results and cancel endpoints.
- Request validation and
extractor_idpin resolution, with their real errors: an unpinned id is400with the available majors, someone else’s@draftis403, an unknown extractor404, a yanked version410. You can test these with a test key on any extractor a live key could call. - Response shapes, the batch and job lifecycle, result retention and webhooks (really sent and signed).
Different from live:
- No page is fetched. Results are simulated (next section).
- Every response carries an
X-Sandbox: trueheader, and the bodies carry"sandbox": true: the extractresult, batch and job status, batch results and webhookdata. - Costs are
0. Sandbox requests appear in your request logs with cost 0 but never in billing or usage, and they never trigger billing emails. - A separate rate limit: 30 requests per minute per account, shared by all your test keys. Sandbox batches take at most 50 targets.
Where the sandbox data comes from
A sandbox result has the same shape as a live one, but the extracted data comes from what ExtractHub already knows about the pinned version, in this order:
- The last passing health check of that version. If the extractor is health-checked (public extractors are checked on a schedule, private ones when you turn checks on), this is real output from a recent probe. See scraper monitoring for how health checks work.
- The released sample output: the result stored when the version was released.
- A placeholder built from the output schema. It is deterministic (same schema, same data) and the values follow the field names and types: a URL field gets an
https://example.com/sandbox/...link, a numericpricegets19.99, aratinggets4.5, a list gets two items. For@draftthe schema is derived from the draft.
metadata.sandboxSource tells you which one you got: health_check, released_sample or schema_fixture. Because the shape follows the output schema, the sandbox is a good place to test your parsing code against the version’s contract.
Your first sandbox request
An illustrative example: a product extractor @you/example-product@1 and a page on example.com.
curl -i -X POST "https://api.extracthub.io/api/extractor/extract" \
-H "X-API-Key: $EXTRACTHUB_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"extractor_id": "@you/example-product@1",
"target": { "url": "https://www.example.com/p/1001" }
}'
The answer (headers and body trimmed):
HTTP/1.1 200 OK
X-Sandbox: true
X-Extractor-Version: 1.2.0
{
"success": true,
"result": {
"extracted": { "title": "Sample title", "price": 19.99, "rating": 4.5 },
"metadata": {
"url": "https://www.example.com/p/1001",
"scrapedAt": "2026-11-15T08:00:00.000Z",
"costUsd": 0,
"sandboxSource": "schema_fixture"
},
"sandbox": true
}
}
The X-Extractor-Version header and the pin rules are the live ones, so a test that checks which version answered behaves the same in production. With options.returnRawHtml: true you get a placeholder HTML comment instead of a page, because nothing was fetched.
Simulate failures with sandbox_scenario
sandbox_scenario goes in the POST body, the GET query string, a batch body or a single batch target. Six values exist:
| Scenario | Realtime extract | Batch |
|---|---|---|
success (default) | 200 with the simulated result | every URL succeeds |
failed | 502 upstream_error | URLs fail with upstream_error |
timeout_to_job | 202 async job; 503 queue_timeout with async_fallback=false | like success |
slow | 200 after about 4 seconds | each URL takes about 4 seconds |
insufficient_credit | 402 insufficient_balance | pauses halfway, then resumes |
insufficient_credit_expired | 402 insufficient_balance | pauses halfway, then fails |
An unknown value is 400 validation_error. A live key that sends sandbox_scenario also gets 400 validation_error: the parameter is rejected, never ignored. So a test written for the sandbox cannot quietly run a real, charged scrape if someone puts a live key in its environment.
Error handling: failed and insufficient credit
The failed scenario returns the same error body as a real scraping failure:
{
"success": false,
"error": "...",
"errors": [{ "code": "upstream_error", "message": "..." }],
"requestId": "..."
}
Branch on errors[0].code, never on the message text. The insufficient-credit scenarios answer 402 with the usual insufficient_balance body, including the top_up_url field, so you can check that your app shows the top-up link instead of a generic error.
Timeouts and async jobs: timeout_to_job
In production, a realtime request that waits too long for scraping capacity becomes an async job: a 202 with job_id, status_url and result_url (unless you sent async_fallback: false, in which case it is a 503 queue_timeout with Retry-After). This is rare, which is exactly why the code path is usually untested. timeout_to_job forces it:
curl -X POST "https://api.extracthub.io/api/extractor/extract" \
-H "X-API-Key: $EXTRACTHUB_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"extractor_id": "@you/example-product@1",
"target": { "url": "https://www.example.com/p/1001" },
"webhook_url": "https://hooks.example.com/extracthub",
"sandbox_scenario": "timeout_to_job"
}'
You get a 202 with a Location and a Retry-After header, and "sandbox": true in the body. The sandbox job completes shortly after: poll status_url (the result is inline once the job completed) or result_url, and your webhook receives job.completed. Run it a second time with "async_fallback": false to test the 503 branch.
Timeouts on your side: slow
slow answers after about 4 seconds. Set your HTTP client timeout below that and you can check what your code does when a request takes longer than you planned for: a retry, a fallback to a job, or an error shown to the user.
Test batches and webhooks end to end
The batch scenarios are where the sandbox saves the most time, because the live versions of these paths depend on your balance running out.
A batch can mix outcomes per URL. At target level, success, failed, slow and timeout_to_job are allowed (timeout_to_job behaves like success in a batch):
{
"extractor_id": "@you/example-product@1",
"targets": [
{ "url": "https://www.example.com/p/1001" },
{ "url": "https://www.example.com/p/1002", "sandbox_scenario": "failed" },
{ "url": "https://www.example.com/p/1003", "sandbox_scenario": "slow" }
],
"webhook_url": "https://hooks.example.com/extracthub"
}
That gives you one succeeded line, one failed line with upstream_error and one late line in the NDJSON results, which is enough to check that your results reader follows the cursor, honours Retry-After and joins lines back by index.
The two credit scenarios go at batch level, and they rehearse the pause:
insufficient_credit: the batch runs the first half of its URLs, then pauses aspaused_insufficient_creditand sendsbatch.paused. It resumes at the first sweep at least one minute after the pause (sweeps run every 5 minutes) and completes withbatch.completed. A one-URL batch pauses right at submission.insufficient_credit_expired: it pauses the same way, then the sweep stops it: statusfailed,failure_reason: "insufficient_credit", eventbatch.failed.
Sandbox webhooks are real HTTP requests to your receiver, signed with your webhook secret the same way as live ones (X-Webhook-Signature: t=...,v1=...), and they use your account default webhook when the request has no webhook_url. The event data has sandbox: true. Two things to check with them:
- Your signature check accepts sandbox events: the secret and scheme are the live ones, so if it fails here, it fails in production.
- Your handler does something sensible with
data.sandbox: true, for example logging the event without writing to production tables, if test and production share one receiver.
Use the sandbox in CI
A test key fits a CI job well: no credit, no target site involved, deterministic data when the result comes from the schema placeholder. A few habits make it safe:
- Keep the test key in its own secret (say
EXTRACTHUB_TEST_KEY), separate from the live key your app uses. - Assert
X-Sandbox: trueon the first response of a test run and abort if it is missing. A test withoutsandbox_scenariowould otherwise run live with a live key. Requests with a scenario already fail with400. - Stay under 30 requests per minute across the whole suite, or treat
429 rate_limitedas a reason to wait, not a test failure. - Don’t assert exact extracted values when the source can be
health_check: that data changes when a new health check passes. Assert the shape (field names and types from the output schema) instead.
From an AI agent over MCP
The MCP server takes test keys too, which makes it a safe way to let an agent explore. The extract, job and batch tools call the REST routes with your key, so every scenario above works there (sandbox_scenario is a tool argument), and get_account reports key_mode: "test". A test key can also run validate_extractor_config. Creating, updating and releasing extractors write real data, so those tools need a live key and answer live_key_required for a test key.
When to switch to a live key
The sandbox proves your integration handles every answer the API can give. It cannot tell you whether an extractor matches a real page today. Before going live, run a few real requests with a live key on pages you know, then keep the test key for CI and local development. Live requests are charged per URL at the extractor version’s tier; see the pricing section. The full list of endpoints, fields and error codes, including the sandbox rules, is in the API reference.
FAQ
How do I test a web scraping API without spending credit?
Use a test API key (exth_test_...). It runs the same endpoints, validation and response shapes as a live key, but never fetches a page and never moves credit, and the sandbox_scenario parameter picks the outcome: a failure, a slow answer, an async job or an empty balance.
Do sandbox requests cost anything?
No. Requests made with a test API key (exth_test_...) never fetch a page and never move credit: every cost is 0 and nothing appears in billing or usage. They still count toward a separate sandbox rate limit of 30 requests per minute per account.
Where does sandbox data come from?
From the pinned version's last passing health check, else the sample output stored when the version was released, else a deterministic placeholder built from its output schema. The metadata.sandboxSource field of each result says which one you got.
Are webhooks sent in the sandbox?
Yes. Sandbox batches and jobs send real webhook requests, signed with your webhook secret like live ones, and the event data carries sandbox: true so your receiver can tell them apart.
What happens if I send sandbox_scenario with a live key?
The request is rejected with 400 validation_error. The parameter is never ignored, so a test that believes it simulates a failure can never run a real, charged scrape instead.
Related
- CSS selectors that survive a redesign: robust selectors for web scraping: Robust CSS selectors for scraping: test ids, itemprop and semantic tags over generated classes, attributes over display text, scoping and fallbacks.
- How to scrape JavaScript rendered pages: when you really need a headless browser: How to scrape JavaScript rendered pages: check the raw HTML first, read embedded JSON, capture XHR responses, add waits and browser actions only when needed.
- Batch web scraping: thousands of URLs with one API call: How a batch web scraping API works: submit up to 1000 URLs, poll progress, page through NDJSON results with a cursor, get signed webhooks and cancel.
- Agent skill: install the extractor builder skill for Claude Code
- MCP server: connect Claude Code, Cursor or any MCP client
- API reference: realtime extract, async jobs and the Batch API
- Web scraper catalog: public extractors you can call today