---
title: Extractions
description: Extract typed field values from shared state.
url: "https://ai-sdk.dev/docs/ai-sdk-core/extractions"
docs_index: /llms.txt
---

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

`experimental_extract` pulls typed values out of one shared state using an
extraction model: an invoice number, a total, a due date, a list of names. Each
field is described once and comes back as one typed answer. State can be a
string, JSON object, or an array of ordered text, file, and JSON parts, the same
as [decisions](/docs/ai-sdk-core/decisions).

This API and the extraction model specification are experimental and may change
in patch releases. Pass an extraction model instance.

```ts
import { experimental_extract, type Experimental_ExtractionModel } from 'ai';

async function readInvoice(model: Experimental_ExtractionModel, text: string) {
  return experimental_extract({
    model,
    state: text,
    referenceDate: '2026-11-11',
    fields: {
      invoiceNumber: { type: 'text', instructions: 'The invoice number' },
      total: {
        type: 'number',
        instructions: 'Total amount due',
        unit: 'USD',
        decimals: 2,
      },
      dueDate: { type: 'date', instructions: 'Payment due date' },
      contacts: { type: 'list', items: 'text', instructions: 'Contact names' },
    },
  });
}

const { answers } = await readInvoice(
  model,
  'Invoice INV-2041, total due $1,250.00 by March 3. Contacts: Ana, Bo.',
);

answers.total.value; // number | null
answers.dueDate.value; // string | null, e.g. '2027-03-03'
answers.contacts.value; // string[] | null
```

`referenceDate` is an optional `YYYY-MM-DD` date that anchors relative dates and
dates without a year.

## Field types

Every field has a `type` and optional `instructions`. Instructions accept
strings, JSON objects, or JSON arrays.

| Type       | Value                                                 | Options                                                                                           |
| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `text`     | `string`                                              | None                                                                                              |
| `number`   | Finite `number`                                       | `unit` (e.g. `'USD'`), `integer`, `decimals` (0 to 6)                                             |
| `date`     | `'YYYY-MM-DD'`, a real calendar date                  | None                                                                                              |
| `time`     | `'HH:MM'` or `'HH:MM:SS'`                             | None                                                                                              |
| `datetime` | ISO 8601 date and time, with an offset when available | None                                                                                              |
| `duration` | Nonnegative `number` in `unit`                        | `unit` (`seconds`, `minutes`, `hours`, `days`, `weeks`, `months`, `years`), `integer`, `decimals` |
| `list`     | `string[]` or `number[]`                              | Required `items` (`'text'`, `'number'`, or `'date'`), `integer` and `decimals` for numbers        |

Answer value types are inferred from the field definitions.

## Answers

Every answer has the field's `type` and a `value`. `value` is `null` when the
state does not contain a value for the field. Models can add:

- `pNull`: probability in \[0, 1] that the state does not contain a value.
- `confidence`: confidence in \[0, 1] that `value` is correct.
- `guess`: the most likely value, also when `value` is `null`. Not on lists.
- `source`: where the value was found. Not on lists.
  - `{ type: 'text', part, start, end }`: `state[part].text.slice(start, end)`,
    with offsets in UTF-16 code units, so the slice works directly in JavaScript.
    A string state is part `0`.
  - `{ type: 'file', part }`: the value was read from the file at `state[part]`.

List answers can include `items`, one `{ confidence?, source? }` entry per value.

## 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`. Invalid answers and refusals are not
retried, and partial results are not supported.

## Testing

Use `Experimental_ExtractionMockModelV4` from `ai/test`:

```ts
import { experimental_extract } from 'ai';
import { Experimental_ExtractionMockModelV4 } from 'ai/test';

const result = await experimental_extract({
  model: new Experimental_ExtractionMockModelV4({
    doExtract: async () => ({
      answers: { total: { type: 'number', value: 1250 } },
      warnings: [],
    }),
  }),
  state: 'Total due: $1,250.00',
  fields: { total: { type: 'number', decimals: 2 } },
});
```

## Provider specification

`Experimental_ExtractionModelV4` is exported from `@ai-sdk/provider` and declares
`specificationVersion: 'v4'`, `provider`, `modelId`, `supportedFieldTypes`, and
`doExtract(options)`. Extraction models are isolated from stable `ProviderV4`.

---

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)