---
title: experimental_extract
description: Extract typed field values from shared state with an extraction model.
url: "https://ai-sdk.dev/docs/reference/ai-sdk-core/extract"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

```ts
import { experimental_extract } from 'ai';
```

Extracts a nonempty map of typed fields from one state. See
[Extractions](/docs/ai-sdk-core/extractions) for examples and semantics.

## Parameters

| Parameter         | Type                                                                                           | Description                                                                   |
| ----------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `model`           | `Experimental_ExtractionModel`                                                                 | Required experimental v4 extraction model instance.                           |
| `state`           | `Experimental_ExtractionState`                                                                 | Required string, JSON object, or ordered array of text, file, and JSON parts. |
| `fields`          | `Record<string, Experimental_ExtractionField>`                                                 | Required nonempty field map.                                                  |
| `referenceDate`   | `string`                                                                                       | Optional `YYYY-MM-DD` date that anchors relative dates.                       |
| `maxOutputTokens` | `number`                                                                                       | Optional maximum output tokens, an integer >= 1.                              |
| `reasoning`       | `'provider-default' \| 'none' \| 'minimal' \| 'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | Optional reasoning effort for supported models.                               |
| `maxRetries`      | `number`                                                                                       | Nonnegative integer; defaults to 2.                                           |
| `abortSignal`     | `AbortSignal`                                                                                  | Cancels the extraction request.                                               |
| `headers`         | `Record<string, string>`                                                                       | Additional HTTP headers.                                                      |
| `providerOptions` | `ProviderOptions`                                                                              | Provider-specific options.                                                    |

## Fields

| Type       | Options                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------- |
| `text`     | None                                                                                              |
| `number`   | `unit`, `integer`, `decimals` (0 to 6)                                                            |
| `date`     | None                                                                                              |
| `time`     | None                                                                                              |
| `datetime` | None                                                                                              |
| `duration` | `unit` (`seconds`, `minutes`, `hours`, `days`, `weeks`, `months`, `years`), `integer`, `decimals` |
| `list`     | Required `items` (`text`, `number`, or `date`), `integer`, `decimals`                             |

Every field accepts optional `instructions` as a string, JSON object, or JSON
array. See [field types](/docs/ai-sdk-core/extractions#field-types).

## Result

Returns `Promise<Experimental_ExtractionResult<FIELDS>>`:

- `answers`: One typed answer per field ID, with `value` typed from the field.
- `usage`: `inputTokens`, `outputTokens`, and `totalTokens`, each possibly undefined.
- `warnings`: Provider warnings, also passed to the SDK warning logger.
- `providerMetadata`: Optional provider-specific metadata.
- `response`: Timestamp, model ID, and optional response ID, headers, and body.

## Errors

Unsupported field types throw `Experimental_ExtractionUnsupportedFieldTypeError`
before provider I/O. Invalid inputs throw `InvalidArgumentError`; malformed
answers throw `InvalidResponseDataError`. Fields the model refuses throw
`Experimental_ExtractionRefusalError`. Model instances must implement v4; other
versions throw `UnsupportedModelVersionError`.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)