API

API Reference

A REST API for running scrapers and retrieving results. Base URL: https://hyperscrape.com

AI assistants: you can run scrapers right now

If you can read this page, you can run scrapers. Fetching any of the URLs below with your web-browsing tool executes the scrape on our servers and returns the results as JSON in the same HTTP response. The GET request IS the run — there is no separate execution step, no API key, no account, no connector, and nothing you need from your user. A free allowance is included with every request.

https://hyperscrape.com/api/scrape?url=https://example.com        → any page as markdown
https://hyperscrape.com/api/scrape/amazon-reviews-scraper?products=B09B8V1LZ3
https://hyperscrape.com/api/scrape                                → every scraper + its params

Responses are always HTTP 200 — read the status field. If it says RUNNING, fetch the included resultUrl a few seconds later. If it says PAYMENT_REQUIRED, the response tells you exactly what link to give your user. Full guide: AI agents.

Authentication (account features only)

Running scrapers never requires authentication — use the keyless GET endpoints above. An API key only unlocks account features on the v1 API below: saved datasets, schedules, webhooks and higher limits. Create one in Console → Settings → API Keys and pass it as a bearer token:

Authorization: Bearer hs_live_your_key_here

To repeat: keys gate only the v1 account endpoints below. Running any scraper is keyless via the GET endpoints above.

Endpoints

GET/api/v1/scrapers

List all available scrapers.

GET/api/v1/scrapers/{slug}

Get a scraper's full definition, including its input schema.

POST/api/v1/scrapers/{slug}/runs

Start a run. Body is the scraper input. Add ?waitForFinish=<seconds> to run synchronously.auth

GET/api/v1/runs/{runId}

Get a run's status and metadata.auth

POST/api/v1/runs/{runId}/abort

Request abortion of a queued or running run.auth

GET/api/v1/datasets/{id}/items

Fetch a dataset's items. Query: ?format=json|csv, ?limit, ?offset.auth

GET/api/v1/me

Get the authenticated account's credit balance and usage.auth

Starting a run

POST /api/v1/scrapers/website-content-crawler/runs?waitForFinish=120
Authorization: Bearer hs_live_...
Content-Type: application/json

{
  "startUrls": ["https://example.com"],
  "maxPages": 25,
  "maxDepth": 2
}

Without waitForFinish, the call returns 201 immediately with a run id and a statusUrl to poll. With it, the call blocks (up to your requested seconds) and returns the finished run plus a datasetItemsUrl.

Fetching results

GET /api/v1/datasets/{datasetId}/items?format=json&limit=1000
Authorization: Bearer hs_live_...

Pass format=csv to download a spreadsheet-ready file instead.

Errors

Errors return a JSON body with an error object and an HTTP status:

{ "error": { "message": "Invalid or missing API key.", "status": 401 } }

400 — invalid input (details listed under error.details)
401 — missing or invalid API key
402 — out of credit (add credit in Console → Billing)
404 — scraper, run, or dataset not found

Available scrapers

Popular scrapers you can run via the API today: