Reference

API basics

Everything on one page: where to call, how to sign in, and what an answer looks like. The routes themselves are in the API reference. The same routes are offered to an assistant as MCP tools.

Address and key

The base address is the same for everyone:

https://portal.scrapewise.ai/api/scraper-api

A path such as /api/key/whoami in these docs means that base address followed by the path.

You sign in with a key. Make it in the portal: your name at the bottom of the portal menu, then API Keys (see Read or Full). There are two kinds:

Key	What it can do
Read	Look at your data. It cannot create, run, change or delete anything.
Full	Everything a Read key can, and also create, run, change and delete.

Send the key in a header on every call. Never put it in the address. The code examples use $SCRAPEWISE_KEY (or $SCRAPEWISE_READ_KEY and $SCRAPEWISE_FULL_KEY) for your key. Set it in your terminal first, for example export SCRAPEWISE_KEY=your_key_here, or in PowerShell $env:SCRAPEWISE_KEY="your_key_here". See Read or Full for which key to use.

Authorization: Bearer YOUR_KEY

bash

curl -H "Authorization: Bearer $SCRAPEWISE_KEY" \
  "https://portal.scrapewise.ai/api/scraper-api/api/key/whoami"

python

import os, requests

r = requests.get(
    "https://portal.scrapewise.ai/api/scraper-api/api/key/whoami",
    headers={"Authorization": f"Bearer {os.environ['SCRAPEWISE_KEY']}"},
)
print(r.status_code, r.json())

javascript

const r = await fetch("https://portal.scrapewise.ai/api/scraper-api/api/key/whoami", {
  headers: { Authorization: `Bearer ${process.env.SCRAPEWISE_KEY}` },
});
console.log(r.status, await r.json());

The answer names your account and the key’s scope. A 401 means the key is wrong or revoked.

Headers

Header	When	Value
`Authorization`	every call	`Bearer YOUR_KEY`
`Content-Type`	calls with a body	`application/json`
`Idempotency-Key`	calls that change something	A new unique text (a UUID is fine) for each new request

To make a new unique text, run uuidgen (Mac, Linux), [guid]::NewGuid() (PowerShell) or crypto.randomUUID() (JavaScript).

Send a new Idempotency-Key on every call that changes or starts something (PUT, PATCH, DELETE, and the POST calls that start work). If your network breaks and you retry the same request with the same key, it is answered once and charged once. A call that needs the header and does not get it answers 400 with IDEMPOTENCY_KEY_REQUIRED.

Placeholders and ids

In the examples, text in square brackets such as [GROUP ID], [SCRAPER ID] or [NEW UUID] is a value you fill in. [NEW UUID] is a fresh unique text (see Headers above). Find your ids with a Read key: groups with GET /api/scraper/group/list, scrapers with GET /api/scraper/list (filter with groupId), and the run id of a scraper in GET /api/scraper/load-history. In the portal, a group’s id is in the address of its data page.

Paging

Lists of rows take page (starts at 0), size (at most 10,000) and sort (field,asc or field,desc). The answer says totalElements and totalPages. Stop when you have read the last page.

GET /api/scraper/data/group/GROUP_ID?page=0&size=1000&sort=createdAt,desc

For big groups add pad=false. The answer then has hasMore and a nextCursor. Copy its key, id and sort into cursor, cursorId and cursorSort on the next call, and keep the same sort, filters and size. Stop when hasMore is false. See Exports and delivery.

Limits

Limits are counted per account: all keys of one account share them. Every answer carries X-RateLimit-Remaining. Over the limit you get 429 with a Retry-After header: wait that many seconds, then try again, slower. Prefer big pages to many small calls. The MCP gateway has its own limits per key and per address, and answers 429 too. See Connect your assistant (MCP).

Errors

An error answer has an errors list. Switch on errors[0].code. It is stable; the message is for people.

json

{
  "errors": [
    { "code": "WALLET_INSUFFICIENT_BALANCE", "message": "Insufficient wallet balance. Top up to continue.", "correlationId": "[ID]" }
  ]
}

Send the correlationId when you write to support. All statuses and codes are on Errors.

Money

Amounts in answers end in Micros: 1,000,000 is EUR 1. A 402 means the wallet is too low: top up, then repeat. See Wallet and billing.

Questions

Which routes can my key call?

A Read key the routes that only read. A Full key every route in the API reference. Sign-in, top-up and key management are done in the portal and are not part of the API.

Is there a test address?

No. Use a Read key to look around safely. Paid calls tell you the price first where they offer a quote, see MCP safety.

How do I find the spec?

Open the API reference for the page, or download openapi-customer.json for a client generator.

Last updated 19 October 2026