# Any public web page as HTML, markdown or text: `POST /v1/scrape`

Cost: 1 credit (1 for a plain fetch, 5 with `render`, 10 with `premium`, 75 with both. Only a 2xx page with content is charged: a block, an error page, an empty page and failed requests are free). Docs: https://scrapercompany.com/docs/reference/scrape

Fetch one public URL and return its content with the upstream status.

By default the page comes back as served; `render=true` runs the page's
JavaScript and returns the DOM after
`domcontentloaded`, an optional `wait_for` CSS selector and `wait_ms`,
with images, media and fonts blocked unless `block_resources=false`, and
an optional PNG `screenshot`. `format` picks `html`, `markdown` or `text`;
markdown and text drop scripts, styles, navigation, footers and iframes
and make every link absolute.

A request the site refuses (403, 429, a bot-check page) is retried
automatically; `premium=true` uses the premium network from the first
attempt; `country` keeps the request in that country; `session_id`
keeps the same IP address across requests.

The answer is a 200 carrying the upstream `status_code`; only a 2xx with
non-empty `content` is charged (1 credit, 5 with render, 10 with premium,
75 with both). A target that refuses every attempt is a 503, an
HTTP 402 (pay-per-crawl) is returned as is and never retried elsewhere,
and private, loopback and cloud-metadata addresses — the URL, a redirect
or anything a rendered page loads — are refused (422). A `timeout_s` that
runs out, or a `wait_for` that never appears, is a 503 that says to
retry or allow more time. All of those are free.

Request body (JSON):

- `url` (string; required; min length 1, max length 2048): The page to fetch: an absolute `http://` or `https://` URL on port 80, 443, 8080 or 8443. Private, loopback and cloud-metadata addresses, and hosts on the scrape denylist, are refused (422), as is any redirect to one; at most 5 redirects are followed.
- `render` (boolean; optional; default false): Run the page's JavaScript and return the DOM after `domcontentloaded` and any `wait_for`/`wait_ms`. Needed for pages that build their content with JavaScript. 5 credits instead of 1.
- `premium` (boolean; optional; default false): Use the premium network from the first attempt, for sites that block standard requests. 10 credits (75 with `render`).
- `country` (string | null; optional; one of AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UK, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW): Two-letter country (ISO 3166-1) the request must come from, e.g. `DE`. Only routes verified in that country are used; when none is available the answer is a 503.
- `wait_for` (string | null; optional; min length 1, max length 500): CSS selector to wait for after `domcontentloaded` (attached to the DOM, visible or not), e.g. `#prices .row`. Never appearing within `timeout_s` is a 503 with Retry-After: retry, or allow more time. Needs `render`.
- `wait_ms` (integer; optional; default 0; min 0, max 10000): A further fixed wait, in milliseconds (0-10000), after the page and any `wait_for`. Needs `render`.
- `block_resources` (boolean; optional; default true): Abort image, media and font requests while rendering: faster, and the DOM is the same. Set false, with `render`, to load them (for a screenshot that shows images).
- `format` (string; optional; default html; one of html, markdown, text): `html` (the page as served, or the rendered DOM), `markdown` or `text`. Markdown and text drop scripts, styles, `noscript`, SVG, `nav`, `footer` and iframes, and make links absolute. A non-HTML text answer (JSON, XML, plain text) comes back as served, with `format: raw`.
- `screenshot` (boolean; optional; default false): Add a PNG screenshot (base64, `screenshot`) of the viewport (1440x900). No extra credits. Needs `render`.
- `full_page` (boolean; optional; default false): Screenshot the whole page instead of the viewport. Needs `screenshot`.
- `headers` (object; optional): Headers to send to the target, e.g. `Accept-Language` or a `Cookie` you hold for the site. Hop-by-hop headers, `Host`, `Content-Length`, `Proxy-*` and anything named like an API-key header (`X-API-Key`) are dropped; `Authorization` and `Cookie` are not sent on to another host after a redirect. With `render` they go with the page request only. At most 32.
- `timeout_s` (integer; optional; default 30; min 1, max 90): Seconds the whole request may take, every attempt and redirect included: at most 60, or 90 with `render`. Running out is a 503 with Retry-After: retry, or allow more time.
- `session_id` (string | null; optional; pattern ^[A-Za-z0-9_-]{1,64}$): Keep the same IP address across requests that share this id (letters, digits, `_`, `-`; up to 64); ids are scoped to your API key. The IP address changes if it stops working.

Base URL: `https://api.scrapercompany.com`. Auth: send your key in the `x-api-key` header. A failed request (4xx or 5xx) or an empty result costs 0 credits.

- [Full API reference as one Markdown file](https://scrapercompany.com/llms-full.txt)
- [OpenAPI spec](https://scrapercompany.com/openapi.json)