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_id pin resolution, with their real errors: an unpinned id is 400 with the available majors, someone else’s @draft is 403, an unknown extractor 404, a yanked version 410. 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: true header, and the bodies carry "sandbox": true: the extract result, batch and job status, batch results and webhook data.
  • 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:

  1. 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.
  2. The released sample output: the result stored when the version was released.
  3. 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 numeric price gets 19.99, a rating gets 4.5, a list gets two items. For @draft the 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:

ScenarioRealtime extractBatch
success (default)200 with the simulated resultevery URL succeeds
failed502 upstream_errorURLs fail with upstream_error
timeout_to_job202 async job; 503 queue_timeout with async_fallback=falselike success
slow200 after about 4 secondseach URL takes about 4 seconds
insufficient_credit402 insufficient_balancepauses halfway, then resumes
insufficient_credit_expired402 insufficient_balancepauses 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 as paused_insufficient_credit and sends batch.paused. It resumes at the first sweep at least one minute after the pause (sweeps run every 5 minutes) and completes with batch.completed. A one-URL batch pauses right at submission.
  • insufficient_credit_expired: it pauses the same way, then the sweep stops it: status failed, failure_reason: "insufficient_credit", event batch.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:

  1. Your signature check accepts sandbox events: the secret and scheme are the live ones, so if it fails here, it fails in production.
  2. 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: true on the first response of a test run and abort if it is missing. A test without sandbox_scenario would otherwise run live with a live key. Requests with a scenario already fail with 400.
  • Stay under 30 requests per minute across the whole suite, or treat 429 rate_limited as 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.

All posts