---
title: "Read one page (scrape)"
method: POST
path: "/api/v1/scrape"
tags: ["Pages"]
---

# Read one page (scrape)

`POST /api/v1/scrape`

## Request

- Base URL: `https://unbrowse.ai`
- URL: `https://unbrowse.ai/api/v1/scrape`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://unbrowse.ai/authorize`, token URL `https://unbrowse.ai/oauth/token`, scopes: `unbrowse`)
  - HTTP bearer

One page by URL, for drop-in migration from hosted scrape APIs. The same path as the `unbrowse_scrape` MCP tool: plain HTTP when the server's HTML carries the content, else Unbrowse's cloud browser renders it. Charged as one verified call only on success. It never runs past `deadlineMs` (default 45 s, clamped 5–120 s). Every answer carries `metadata.statusCode` / `metadata.status` (the page's real HTTP status, also when rendered), `timing` (ms, httpMs, renderMs, queuedMs) and `attempts` (HTTP tries); every error carries the same in `error.details`, with `stage` (http or render), `reason`, `httpStatus` and `renderStatus`.

Errors: 400 invalid input; 402 out of calls; 429 `blocked` (a bot check or an empty page over HTTP and in the browser) with a `Retry-After` header when the page is remembered as walled — for 10 minutes the same host, country and path answer 429 at once; 504 `scrape_timeout` when the deadline passed.

## Request body

- object
  - `url` string, required: The page, e.g. https://example.com/pricing (https:// is assumed when missing).
  - `country` string: Exit country: a two-letter ISO code (US, GB, DE…) or GLOBAL.
  - `formats` string[]: What to return (default ["html"]). raw: the body as sent, over HTTP only.
  - `format` 'raw_html': Convenience: the whole page's HTML (formats ["html"] with onlyMainContent false).
  - `onlyMainContent` boolean: Drop navigation, headers, footers and asides (default true).
  - `render` 'auto' | 'always' | 'never': auto (default): HTTP first, the browser only when the page needs it.
  - `deadlineMs` number: Overall time budget in ms (default 45000).

## Response `200`

The page

- object
  - `html` string
  - `markdown` string
  - `text` string
  - `links` string[]
  - `raw` string
  - `via` 'http' | 'rendered'
  - `metadata` object
    - `statusCode` integer
    - `status` integer
    - `url` string
    - `finalUrl` string
    - `title` string
  - `timing` object
    - `ms` number
    - `httpMs` number
    - `renderMs` number
    - `queuedMs` number
  - `attempts` integer: HTTP tries (fresh IPs).

## Other responses

- `400`: An error
- `401`: Either the Unbrowse credentials are missing or invalid (`error.code` `unauthorized`; the WWW-Authenticate header names the protected-resource metadata), or the page is behind a sign-in (`error.code` `login_required`, not billed): the read was sent to the site's sign-in page or shown one at the address itself, and Unbrowse has no usable sign-in for the site. `error.details` carries `site`, `finalUrl`, `sessionSent`, `reason` (`login_wall`, `redirect_to_login`) and `next`, the fixes to relay (sync the user's browser sign-in with `unbrowse cookies sync --domain <site>` or the extension, or save a login).
- `402`: An error
- `404`: An error
- `429`: An error
- `504`: An error

---

[API](https://skmtc.dev/unbrowse/apis/unbrowse-api.md) · [All operations](https://skmtc.dev/unbrowse/apis/unbrowse-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unbrowse/apis/unbrowse-api/revisions/f49034a1fbff?raw)