---
title: "Extract"
method: POST
path: "/v1beta/extract"
tags: ["Extract (Beta)"]
---

# Extract

`POST /v1beta/extract`

Extracts relevant content from specific web URLs.

## Headers

- `parallel-beta` string, nullable

## Request body

- ExtractRequest — Extract request.
  - `urls` string[], required
  - `objective` string, nullable — If provided, focuses extracted content on the specified search objective.
  - `search_queries` string[], nullable — If provided, focuses extracted content on the specified keyword search queries.
  - `fetch_policy` FetchPolicy — Policy for live fetching web results.
    - `max_age_seconds` integer, nullable — Maximum age of cached content in seconds to trigger a live fetch. Minimum value 600 seconds (10 minutes).
    - `timeout_seconds` number, nullable — Timeout in seconds for fetching live content if unavailable in cache.
    - `disable_cache_fallback` boolean — If false, fallback to cached content older than max-age if live fetch fails or times out. If true, returns an error instead.
  - `excerpts` union — Include excerpts from each URL relevant to the search objective and queries. Note that if neither objective nor search_queries is provided, excerpts are redundant with full content.
    - boolean
    - ExcerptSettings — Optional settings for returning relevant excerpts.
      - `max_chars_per_result` integer, nullable — Optional upper bound on the total number of characters to include per url. Excerpts may contain fewer characters than this limit to maximize relevance and token efficiency.
      - `max_chars_total` integer, nullable — Optional upper bound on the total number of characters to include across all urls. Results may contain fewer characters than this limit to maximize relevance and token efficiency. This overall limit applies in addition to max_chars_per_result.
  - `full_content` union — Include full content from each URL. Note that if neither objective nor search_queries is provided, excerpts are redundant with full content.
    - boolean
    - FullContentSettings — Optional settings for returning full content.
      - `max_chars_per_result` integer, nullable — Optional limit on the number of characters to include in the full content for each url. Full content always starts at the beginning of the page and is truncated at the limit if necessary.
  - `session_id` string, nullable — Session identifier to track calls across separate search and extract calls, to be used as part of a larger task. Specifying it may give better contextual results for subsequent API calls.
  - `client_model` string, nullable — The model generating this request and consuming the results. Enables optimizations and tailors default settings for the model's capabilities.

## Response `200`

Successful Response

- ExtractResponse — Fetch result.
  - `extract_id` string, required — Extract request ID, e.g. `extract_cad0a6d2dec046bd95ae900527d880e7`
  - `results` ExtractResult[], required — Successful extract results.
    - `url` string, required — URL associated with the search result.
    - `title` string, nullable — Title of the webpage, if available.
    - `publish_date` string, nullable — Publish date of the webpage in YYYY-MM-DD format, if available.
    - `excerpts` string[], nullable — Relevant excerpted content from the URL, formatted as markdown.
    - `full_content` string, nullable — Full content from the URL formatted as markdown, if requested.
  - `errors` ExtractError[], required — Extract errors: requested URLs not in the results.
    - `url` string, required
    - `error_type` string, required — Error type.
    - `http_status_code` integer, nullable, required — HTTP status code, if available.
    - `content` string, nullable, required — Content returned for http client or server errors, if any.
  - `warnings` Warning[], nullable — Warnings for the extract request, if any.
    - `type` 'spec_validation_warning' | 'input_validation_warning' | 'warning', required — Type of warning. Note that adding new warning types is considered a backward-compatible change.
    - `message` string, required — Human-readable message.
    - `detail` object, nullable — Optional detail supporting the warning.
  - `usage` UsageItem[], nullable — Usage metrics for the extract request.
    - `name` string, required — Name of the SKU.
    - `count` integer, required — Count of the SKU.

## Other responses

- `422` — Request validation error

## Changes

> 21 revisions in range; 2 could not be searched.

- **2026-04-22** `66ee13c3475d` — 1 info
  - added the new optional request property `client_model`
- **2026-04-21** `57e1c56be094` — 1 breaking, 4 info
  - for the `header` request parameter `parallel-beta`, default value `search-extract-2025-10-10` was removed
  - added the new optional request property `session_id`
  - `header` request parameter `parallel-beta` was deprecated
  - `header` request parameter `parallel-beta` list-of-types was widened by adding types `null`
  - …1 more
- **2026-01-29** `31ff2f5e2e00` — 1 info
  - the `header` request parameter `parallel-beta` became optional
- **2026-01-13** `105d778ad64d` — 2 breaking, 6 info
  - the `header` request parameter `parallel-beta` became required
  - the `error` response's property type/format changed from ``/`` to `object`/`` for status `422`
  - added the new optional request property `excerpts/anyOf[subschema #2: ExcerptSettings]/max_chars_total`
  - added the optional property `error/detail` to the response with the `422` status
  - …4 more
- …earlier changes not shown

[Full history](https://skmtc.dev/parallel-web/apis/parallel-api/changes/v1beta/extract/post.md)

---

[API](https://skmtc.dev/parallel-web/apis/parallel-api.md) · [All operations](https://skmtc.dev/parallel-web/apis/parallel-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/parallel-web/parallel-api/revisions/1595294c8795/schema)