> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helve.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract

> URLs in, clean content out, across nine providers.

`POST /v1/extract` fetches up to 20 URLs and returns each page as markdown or text. Pass a `query` to get focused excerpts and summaries on providers that support them. Full parameter list: [API reference](/api-reference/extract).

```bash theme={null}
curl -s https://helve.dev/v1/extract \
  -H "Authorization: Bearer $HELVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "urls": ["https://arxiv.org/abs/2211.17192"],
    "query": "how does speculative decoding work",
    "content": { "excerpts": { "max_per_url": 3 } }
  }'
```

## Providers

| Provider    | Focused excerpts      | Summary | Links and images | Freshness control             |
| ----------- | --------------------- | ------- | ---------------- | ----------------------------- |
| `exa`       | Yes                   | Yes     | Yes              | `max_age_hours`, `timeout_ms` |
| `tavily`    | Yes, with `query`     | No      | Images           | `timeout_ms`                  |
| `parallel`  | Yes, objective-driven | No      | No               | No                            |
| `serper`    | No                    | No      | No               | No                            |
| `firecrawl` | Yes                   | No      | No               | No                            |
| `linkup`    | No                    | No      | No               | No                            |
| `valyu`     | Yes                   | Yes     | No               | No                            |
| `jina`      | No                    | No      | No               | No                            |
| `octen`     | No                    | No      | No               | No                            |

Brave and Perplexity have no extraction product and are not accepted for this endpoint.

Providers that take one URL per call are fanned out by Helve, so a 20-URL request costs 20 provider calls on those.

## Partial failure

A page that cannot be fetched does not fail the request. It lands in `failed` with the provider's reason, and the rest come back in `results` with a 200.

```json theme={null}
{
  "id": "ext_01j…",
  "provider": "exa",
  "results": [{ "url": "https://arxiv.org/abs/2211.17192", "title": "…", "content": "…", "excerpts": ["…"], "raw": {} }],
  "failed": [{ "url": "https://example.com/paywalled", "error": "fetch timed out" }],
  "warnings": [],
  "usage": { "cost_usd": 0.001, "credits": 0 },
  "latency_ms": 1420
}
```

## Content options

<ParamField body="content.full_text" type="boolean" default="true">
  The whole page in `content`. Turn it off when you only want excerpts.
</ParamField>

<ParamField body="content.max_chars" type="integer">
  Cap on `content` per URL, 100 to 100,000. Native on Exa; Helve truncates for the others.
</ParamField>

<ParamField body="content.excerpts" type="object">
  Focused passages in `excerpts`, most useful together with `query`.
</ParamField>

<ParamField body="content.format" type="'markdown' | 'text'">
  Native on Tavily and Serper. Most providers return markdown regardless and say so in `warnings`.
</ParamField>