# Extract

> Schema-driven AI extraction for precise structured data.

An **Extraction** pulls precise fields out of a document. By providing a standard **JSON Schema**, you instruct the language model to locate, format, and return a matching JSON object, turning unstructured documents into structured records.

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Raw Document<br/>&#x22;] --> B[&#x22;Language Model<br/>+ User Schema&#x22;]
  B --> C[&#x22;Extracted JSON Output&#x22;]
`"
/>

```json
{
  "totalAmount": 450,
  "invoiceNumber": "..."
}
```

* **Schema Adherence**: the output is validated against your JSON Schema.
* **Complex Data Extraction**: extract nested arrays (like invoice line items) or deep hierarchical objects.
* **Contextual Instructions**: add instructions to guide the model on specific fields.

***

## 🏗️ Configuration

An Extraction is an [Operation](https://docs.axelered.com/jobs_guide): it parses the Document, then extracts the fields.

| Parameter      | Type     | Default              | Description                                                                                                        |
| :------------- | :------- | :------------------- | :----------------------------------------------------------------------------------------------------------------- |
| `outputSchema` | `object` | required             | A JSON Schema of the fields to extract. An invalid schema returns `422 invalid_output_schema` ([Errors](https://docs.axelered.com/errors)). |
| `tier`         | `string` | `fast`               | `fast` or `accurate`. See [Operation Tiers](https://docs.axelered.com/config_guide#-operation-tiers).                                       |
| `instructions` | `string` | none                 | Extra instructions for the model (e.g., "Only extract values in USD").                                             |
| `parsing`      | `object` | `{ "tier": "fast" }` | How the Document is parsed: `tier` and `pages`. See [Parse](https://docs.axelered.com/parse).                                               |
| `perimeter`    | `string` | `external`           | Where your data may go. See [Perimeters](https://docs.axelered.com/config_guide).                                                           |

The model reads the first 20,000 characters of the parsed Document; when it is longer, the Output reports `truncated: true`.

***

## 🛠️ Extract from a Document

For every field and parameter, see the [**Extractions reference**](https://docs.axelered.com/reference#extractions).

### [Submit an Extraction](https://docs.axelered.com/reference/extractions/api_create_extractions_post)

```bash
curl -X POST "https://api.axelered.com/v1/extractions?wait=30" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/invoice.pdf" \
  -F 'config={
    "outputSchema": {
      "type": "object",
      "properties": {
        "invoiceNumber": { "type": "string" },
        "totalAmount": { "type": "number" }
      },
      "required": ["invoiceNumber", "totalAmount"]
    },
    "tier": "accurate",
    "parsing": { "tier": "accurate" }
  }'
```

Once the Extraction is `done`, the extracted object is in its `output`:

```json
{
  "status": "done",
  "output": {
    "value": { "invoiceNumber": "INV-0042", "totalAmount": 450 },
    "truncated": false
  }
}
```

### List, Read & Delete

* [**List Extractions**](https://docs.axelered.com/reference/extractions/api_list_extractions_get): newest first, optionally for one Document with `?documentId=`. Lists leave out the `output`.
* [**Read Extraction**](https://docs.axelered.com/reference/extractions/api_read_extractions__job_id__get): status, credits and `output`, with optional `wait`.
* [**Delete Extraction**](https://docs.axelered.com/reference/extractions/api_delete_extractions__job_id__delete): hide an Extraction. Its Document is kept.