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

# Extract Fields

> Pull structured fields from a parsed document with a JSON Schema, then read the values and check which ones are grounded.

Run `ade extract` to pull the fields you name from a document you have already parsed. A schema defines those fields, and the result comes back shaped like the schema, with a record of where each value was found. Each extraction is its own job item, and it references the parse it ran against rather than copying it.

For a worked example, see the [Quickstart](./quickstart). For the files a run saves, see [CLI Concepts](./concepts).

## Choose Your Input

Extract from a completed parse, from a document path, or from Markdown you hold yourself.

| Input               | What happens                                                                                                                |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| A parse job item ID | Extracts against the stored parse. This is the most common case.                                                            |
| A document path     | Reuses the latest parse of that file if there is one. Otherwise it parses first.                                            |
| Your own Markdown   | Extracts from a Markdown file you supply rather than a parse. With no document behind it, the result has no page locations. |

```bash theme={null}
ade extract 8d1ec099 --schema schema.json              # a completed parse
ade extract -d invoice.pdf --schema schema.json        # a document path
ade extract --markdown notes.md --schema schema.json   # your own Markdown
```

## Write a Schema

A schema is a JSON Schema object naming each field, its type, and a description the model uses to recognize it. Build one visually in the [Playground](https://ade.landing.ai/) and download the JSON, or write it by hand following [Extraction Schema (JSON)](/dpt3/ade-extract-schema-json).

Pass a file path or an inline JSON object. Changing a schema changes the run, so the next extraction is a new job item that consumes credits.

```bash theme={null}
ade extract 8d1ec099 --schema '{"type":"object","properties":{"total":{"type":"number"}}}'
```

### Require Every Field

By default, a field the model cannot extract is skipped, and the run reports `schema_violation_error`. Add `--strict` to make the request fail instead. For everything strict mode covers, see [Extract Input Parameters](/dpt3/extract-input).

```bash theme={null}
ade extract 8d1ec099 --schema schema.json --strict
```

## Read the Result

The extracted values come back under `extraction`, shaped exactly like your schema. For the three-field schema in the [Quickstart](./quickstart), that looks like this:

```json theme={null}
{
  "balance_due": 89.52,
  "medical_record_number": "MRN-100-55-3821",
  "patient_name": "Ada M. Rensford"
}
```

### Check Which Values Are Grounded

A grounded value is one the model read from a specific place on the page. To see where a value came from, open the extraction in the viewer, which highlights the spot on the page each field was read from. [Find, Crop, and View](./find-crop-view) covers the viewer, local search, and cropping evidence images. Three signals tell you where each field stands.

| Signal         | What it tells you                                                                                                             |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `fields`       | How many leaf fields the schema asked for.                                                                                    |
| `ungroundable` | Fields with a value the model could not tie to a location on the page. The value may still be correct, but nothing quotes it. |
| `empty_fields` | Fields with no value at all, so there was nothing to ground.                                                                  |

### Use the Values in a Script

Add `--json` to print the whole payload, then select the `extraction` key with a JSON tool such as `jq`.

```bash theme={null}
ade extract 8d1ec099 --schema schema.json --json | jq .extraction
```

## Choose a Service Tier

Parse and Extract use async jobs, and each submitted job sends a service tier. The CLI defaults to `priority`, the fast lane, which consumes credits at the full rate. The `standard` tier runs in a slower lane and consumes half the credits.

That default differs from the API, where a job that sends no `service_tier` runs on `standard`. If you are moving a workload from the API to the CLI, pass `--tier standard` to keep consumption the same.

For the rates, see [Credit Consumption](/dpt3/credit-consumption). For how the two lanes differ, see [Sync vs Async](/dpt3/sync-async).

Set the tier per run:

```bash theme={null}
ade extract 8d1ec099 --schema schema.json --tier standard
```

## Stale Extractions

An extraction points at the parse it ran against. If you later re-run that parse with `--force`, the extraction keeps its old result, and `ade history list` marks it `stale`. Re-run the extraction to update it.

## Next Steps

<CardGroup cols={2}>
  <Card title="Find, Crop, and View" icon="magnifying-glass" href="./find-crop-view">
    Verify a value by searching the parse and cropping the evidence.
  </Card>

  <Card title="Scripting and Automation" icon="code" href="./scripting-automation">
    Pipe extractions into other tools and run them unattended.
  </Card>
</CardGroup>