Processing modes

The Data Extraction API offers four processing modes that trade off cost, speed, and extraction depth. Every request uses exactly one mode, set via the mode parameter in the instructions.

Mode selection by use case

Start with the output your application needs, and then choose the mode.

Mode comparison

Text mode

Text mode extracts Markdown from born-digital documents. It doesn’t run OCR or AI augmentation, making it the fastest and cheapest option.

curl -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer your_api_key_goes_here" \
  -F "file=@document.pdf" \
  -F 'instructions={"mode":"text"}'

import requests

response = requests.post(
    "https://api.nutrient.io/extraction/parse",
    headers={"Authorization": "Bearer your_api_key_goes_here"},
    files={"file": open("document.pdf", "rb")},
    data={
        "instructions": '{"mode":"text","output":{"format":"markdown"}}'
    },
)

print(response.json()["output"]["markdown"])

import fs from "node:fs";

const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));
form.append(
  "instructions",
  JSON.stringify({ mode: "text", output: { format: "markdown" } }),
);

const response = await fetch("https://api.nutrient.io/extraction/parse", {
  method: "POST",
  headers: { Authorization: "Bearer your_api_key_goes_here" },
  body: form,
});

const result = await response.json();
console.log(result.output.markdown);

When to use text mode

• RAG ingestion and search indexing where you need clean Markdown from born-digital documents
• High-throughput pipelines where cost and speed matter more than spatial data

Limitations

• Only supports markdown output format
• No OCR — text in scanned documents or images won’t be returned

Structure mode

Structure mode runs OCR-based segmentation to extract typed document elements with bounding boxes and confidence scores. It handles scanned documents, images, and any file requiring optical character recognition.

curl -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer your_api_key_goes_here" \
  -F "file=@document.pdf" \
  -F 'instructions={"mode":"structure","output":{"format":"spatial"}}'

import requests

response = requests.post(
    "https://api.nutrient.io/extraction/parse",
    headers={"Authorization": "Bearer your_api_key_goes_here"},
    files={"file": open("document.pdf", "rb")},
    data={
        "instructions": '{"mode":"structure","output":{"format":"spatial"}}'
    },
)

result = response.json()
for element in result["output"]["elements"]:
    print(f'{element["type"]}: {element.get("text", "")}')

import fs from "node:fs";

const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));
form.append(
  "instructions",
  JSON.stringify({ mode: "structure", output: { format: "spatial" } }),
);

const response = await fetch("https://api.nutrient.io/extraction/parse", {
  method: "POST",
  headers: { Authorization: "Bearer your_api_key_goes_here" },
  body: form,
});

const result = await response.json();
result.output.elements.forEach((el) => {
  console.log(`${el.type}: ${el.text || ""}`);
});

When to use structure mode

• Scanned documents and images that require OCR
• Workflows that need spatial data (bounding boxes, coordinates) at lower cost than understand mode
• Documents with straightforward layouts where AI augmentation isn’t necessary
• OCR-backed Markdown from scans when layout complexity is low

Limitations

• May not reliably produce key-value pairs for forms or invoices. Use understand mode for keyValueRegion.pairs, or use /extraction/extract with a schema when you need known fields as JSON.
• Can miss complex table structure, multicolumn layout relationships, and form semantics because it doesn’t use AI augmentation.

Understand mode

Understand mode runs the full extraction pipeline with AI augmentation on top of OCR. It produces the most accurate results for complex documents with tables, multicolumn layouts, nested structures, formulas, and form fields.

curl -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer your_api_key_goes_here" \
  -F "file=@document.pdf" \
  -F 'instructions={"mode":"understand","output":{"format":"spatial"}}'

import requests

response = requests.post(
    "https://api.nutrient.io/extraction/parse",
    headers={"Authorization": "Bearer your_api_key_goes_here"},
    files={"file": open("document.pdf", "rb")},
    data={
        "instructions": '{"mode":"understand","output":{"format":"spatial"}}'
    },
)

result = response.json()
for element in result["output"]["elements"]:
    print(f'{element["type"]}: {element.get("text", "")}')

import fs from "node:fs";

const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));
form.append(
  "instructions",
  JSON.stringify({ mode: "understand", output: { format: "spatial" } }),
);

const response = await fetch("https://api.nutrient.io/extraction/parse", {
  method: "POST",
  headers: { Authorization: "Bearer your_api_key_goes_here" },
  body: form,
});

const result = await response.json();
result.output.elements.forEach((el) => {
  console.log(`${el.type}: ${el.text || ""}`);
});

When to use understand mode

• Complex documents with tables, multicolumn layouts, or nested structures
• Invoice and form processing where accurate data extraction matters
• Form and key-value extraction where you need keyValueRegion.pairs in spatial output
• Documents with formulas, tables, printed-style handwriting, or mixed content types
• Any workflow where extraction accuracy is more important than cost

If you already know the fields you want, such as invoice_number, vendor_name, or total_amount, consider the /extraction/extract endpoint instead of reconstructing fields from spatial elements.

Agentic mode

Agentic mode builds on the understand pipeline and augments it with a VLM. The VLM improves results in areas like image descriptions, complex layout analysis, and semantic understanding. It’s designed for the most complex documents that require the deepest visual understanding.

curl -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer your_api_key_goes_here" \
  -F "file=@document.pdf" \
  -F 'instructions={"mode":"agentic","output":{"format":"spatial"}}'

import requests

response = requests.post(
    "https://api.nutrient.io/extraction/parse",
    headers={"Authorization": "Bearer your_api_key_goes_here"},
    files={"file": open("document.pdf", "rb")},
    data={
        "instructions": '{"mode":"agentic","output":{"format":"spatial"}}'
    },
)

result = response.json()
for element in result["output"]["elements"]:
    print(f'{element["type"]}: {element.get("text", "")}')

import fs from "node:fs";

const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));
form.append(
  "instructions",
  JSON.stringify({ mode: "agentic", output: { format: "spatial" } }),
);

const response = await fetch("https://api.nutrient.io/extraction/parse", {
  method: "POST",
  headers: { Authorization: "Bearer your_api_key_goes_here" },
  body: form,
});

const result = await response.json();
result.output.elements.forEach((el) => {
  console.log(`${el.type}: ${el.text || ""}`);
});

When to use agentic mode

• Documents with embedded images, charts, or diagrams where you need generated alt descriptions, not just classification
• Degraded scans, faxes, low-quality images, or documents where understand mode produces visible gaps in extracted text
• Cursive, connected, or freeform handwriting — along with dense or annotated handwriting (forms with handwritten markup, filled-in government forms) — where understand mode’s character-level handwriting recognition isn’t sufficient
• Workflows where you’ve tested understand mode on a representative sample and the quality isn’t sufficient for your use case

Limitations

• Slowest processing mode
• 18 credits per page

Choosing the right mode

The default mode is understand, which handles most documents well. Move to a different mode when you have a specific reason:

1. Do you only need Markdown from born-digital documents?
   • Yes — Use text mode. It’s the fastest and cheapest option (1 credit per page), but has no OCR.
   • No — Continue to step 2.
2. Do you need Markdown from scanned documents or images?
   • Yes — Use structure mode with output.format: "markdown" to run OCR before Markdown generation. Move to understand if the layout quality isn’t good enough.
   • No — Continue to step 3.
3. Are you extracting forms, key-value pairs, invoices, or known fields?
   • Yes — Use understand mode with spatial output for keyValueRegion.pairs, or use /extraction/extract with a schema for known fields. Don’t rely on structure mode for form/key-value extraction.
   • No — Continue to step 4.
4. Do your documents need image descriptions or contain cursive handwriting, or has understand mode produced insufficient quality on a representative sample?
   • No — Stay with understand mode (default). It already handles tables, forms, formulas, printed-style handwriting, and multicolumn layouts without VLM.
   • Yes — Use agentic mode. VLM augmentation on top of the understand pipeline adds descriptions for embedded images and a quality lift on degraded scans, cursive or freeform handwriting, and other hard-to-read content where understand mode falls short.

For mixed-complexity pipelines, route documents by type: Use text mode for born-digital PDFs, structure mode for scanned documents with simple layouts, understand mode for most complex documents, and agentic mode when VLM-augmented extraction is needed.

Handwriting

Handwriting recognition depends on both the writing style and the quality of the input image.

Match the mode to the writing style

• Printed-style handwriting — Clearly separated letters and short entries such as names, dates, and filled-in form fields. Understand mode handles this well with character-level OCR.
• Cursive, connected, or freeform handwriting — Use agentic mode. Understand mode reads handwriting one character at a time, so connected or stylized writing produces frequent errors. The VLM in agentic mode interprets whole words and lines and is substantially more reliable for these documents.

Credit costs

See pricing for more details and frequently asked questions (FAQs).