---
title: "Structured data from a page, in a schema you define"
method: POST
path: "/extract"
---

# Structured data from a page, in a schema you define

`POST /extract`

## Request

- Base URL: `https://urlpipe.dev`
- URL: `https://urlpipe.dev/extract`
- Auth: HTTP bearer

24 credit(s) per successful, uncached call. Documentation: https://urlpipe.dev/docs/extract

## Headers

- `Idempotency-Key` string

## Request body

- ExtractRequest
  - `url` string, uri, required: The page to fetch: a public http(s) URL.
  - `sync` boolean: Return the result in the response instead of a token.
  - `report_to` string, uri: Webhook URL the result is POSTed to (async requests).
  - `max_age` union: How fresh a cached result must be: seconds, or a duration like "3 days". Default 7 days, maximum 30; 0 bypasses the cache.
    - integer
    - string
  - `labels` object: Your own ids for this request, returned with the result and the webhook.
  - `residential` boolean: Fetch from a home broadband address. +25 credits per page visit.
  - `page_options` PageOptions
    - `wait_for_selector` string: Wait for this CSS selector, up to 10 seconds.
    - `scroll_to_bottom` boolean: Scroll down the page before reading it, for as long as scrolling loads more, up to 25 seconds.
    - `delay` integer: Milliseconds to wait after the page settles.
    - `block_ads` boolean
    - `block_cookie_banners` boolean
    - `block_popups` boolean: Remove newsletter, app-install and promotional popups laid over the page.
    - `remove_selectors` string[]
  - `fields` ExtractField[], required: The fields to extract, at most 50 in all.
    - `name` string, required: The key in the result.
    - `type` 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'datetime' | 'url' | 'email' | 'object' | 'array', required
    - `description` string: What to take from the page.
    - `fields` ExtractField[]: An object's fields.
    - `items` union: What an array holds: a type name, or a field without a name.
      - 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'datetime' | 'url' | 'email' | 'object'
      - ExtractField (recursive)
  - `instructions` string: Guidance that applies to every field.

## Response `200`

With `sync: true`, the result. Without it, the request was accepted: a token to collect the result with.

- Extraction: One key per requested field, in the order requested. A value the page does not give is null.

## Other responses

- `401`: Missing or invalid API key.
- `403`: The key is valid, but the email address on the account hasn't been confirmed yet.
- `422`: The URL or an option is invalid, or the page could not be fetched (the error says which). Spends nothing.
- `429`: Over the plan's parallel-request limit (`concurrency_limit`), sending too fast (`rate_limited`), or — Free plan only — out of credits (`quota_exceeded`). Spends nothing.
- `504`: A sync request took longer than 60 seconds; the work continues — collect it with GET /result/{token}.

---

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