# Extract structured data from text

Launch stage: GA

`POST /api/2.0/ai-functions/ai-extract`

Extracts structured data from text and documents according to a provided schema.

API scopes: ai-functions

## Request body

- `content` (object, required)
  The text to extract from. It accepts a plain string or the response object of [ai_parse_document](:method:AiFunctions/AiParseDocument).
- `schema` (object, required)
  The extraction schema defining the fields to extract. Either a JSON array of field names, assumed to be strings (e.g. ["company", "valuation"]), or a JSON object mapping each field to its type/description/nullability (e.g. {"company": {"type": "string", "description": "the company name"}}). Accepts up to 256 fields, 12 levels of nesting, and 500 enum values. Supported field types are string, integer, number, boolean, and enum.
- `options` (object, optional)
  Function options. Omitted fields fall back to their documented defaults.
  - `instructions` (string, optional)
    Natural-language guidance that steers how data is extracted (up to 20,000 characters).
  - `version` (string, optional)
    The function version to invoke. Defaults to the latest version. Supported versions: ["2.1"].
  - `mode` (string, optional)
    Extraction mode. Supported modes: "precision" — more powerful extraction for complex schemas, long documents, and reasoning-heavy extractions. Defaults to none (standard extraction).
  - `enable_citations` (boolean, optional)
    When true, includes citation metadata locating each extracted value in the source. Depending on the type of input, citations can be one of two types:
    
     For raw text (STRING) inputs, a citation is a span of text in the original input. Each object in `metadata.citations` has an `id` (integer matching a `citation_ids` entry on a field), a `start` (inclusive 0-based character offset into the input string), and a `stop` (exclusive 0-based character offset into the input string).
    
     For PDF documents and images (when using ai_extract downstream of ai_parse_document), a citation is a bounding box in the original input. Each object in `metadata.citations` has an `id` (integer matching a `citation_ids` entry on a field) and a `bbox` (array of {coord, page_id} objects, identical in shape to element.bbox in ai_parse_document output; coord is pixel coordinates on the page image as [x0, y0, x1, y1], and page_id is a 0-based page index).
  - `enable_confidence_scores` (boolean, optional)
    When true, includes a per-field confidence score in the response.

## Returns

- `response` (object, optional)
  The function result as a JSON value. When `enable_confidence_scores` and `enable_citations` are true, `confidence` and `citation_ids` are included in each response field, respectively.
- `metadata` (object, optional)
  Additional metadata returned by AI Extract.
  - `version` (string, optional)
    The resolved function version.
  - `mode` (string, optional)
    The resolved extraction mode; present when a non-default mode was used.
  - `chunk_type` (string, optional)
    How the source was chunked for citation offsets (span for text input, bbox for parsed-document input); present when citations are enabled.
  - `citations` (array of object, optional)
    Citation objects locating each result in the source; present when citations are enabled.
    - `id` (int64, optional)
      Integer matching a citation_ids entry on an extracted field.
    - `start` (int64, optional)
      Inclusive 0-based character offset into the input string; set for span citations.
    - `stop` (int64, optional)
      Exclusive 0-based character offset into the input string; set for span citations.
    - `bbox` (array of object, optional)
      Bounding boxes locating the citation on the source pages; set for bbox citations.
      - `coord` (array of int64, optional)
        Pixel coordinates on the page image as [x0, y0, x1, y1].
      - `page_id` (int64, optional)
        0-based page index the box is on.

## Response

```json
{
  "response": {},
  "metadata": {
    "version": "string",
    "mode": "string",
    "chunk_type": "string",
    "citations": [
      {}
    ]
  }
}
```