Reducto Documentation | Parse API Overview

Parse is Reducto’s foundational endpoint. It converts documents into structured JSON with text, tables, figures, layout, and formatting, then organizes the content into chunks for LLM consumption, RAG pipelines, or downstream extraction. Each element includes its type, page position, and confidence score. Parse handles multi-column text, nested tables, forms with handwriting, rotated pages, and documents mixing text with charts and images. For a higher-level view of supported use cases and how Parse fits with the rest of the platform, see the Parse product overview.

Try it live: See Parse in action with a sample bank statement in Reducto Studio.

File size limits: Upload files up to 100MB directly via the Upload endpoint, or up to 5GB via presigned URL. You can also pass public URLs or presigned S3/GCS/Azure URLs directly.

Choose a Parse pipeline

Reducto parse r-1 is currently in preview and is the default for all new Parse pipelines. It combines text, table, figure, layout, formatting, and grounding in one full-page model. Existing pipelines can continue using legacy Parse or choose to migrate.

Pipeline	Recommended use	How it works
r-1 preview	All new Parse pipelines and most existing workloads	One full-page model handles text, tables, figures, layout, formatting, and grounding together.
Legacy agentic pipeline	Workflows that require custom prompts or specialized agentic processing	Additional vision-language model passes process relevant text, tables, or figures. This adds latency.
Legacy standard Parse	Existing workflows that depend on legacy behavior or a configuration that r-1 does not support yet	OCR, layout detection, and post-processing run as separate stages.

r-1 replaces the general-purpose use of agentic text, table, and figure scopes. You can combine r-1 with the agentic pipeline when your workflow needs one or more custom prompts or a specialized augmentation such as advanced chart extraction. Reducto runs the relevant agentic components and augments the r-1 result.

Quick Start

from pathlib import Path
from reducto import Reducto

client = Reducto()

upload = client.upload(file=Path("invoice.pdf"))
result = client.parse.run(input=upload.file_id)

for chunk in result.result.chunks:
    print(chunk.content)

import Reducto from 'reductoai';
import fs from 'fs';

const client = new Reducto();

const upload = await client.upload({
  file: fs.createReadStream('invoice.pdf'),
});
const result = await client.parse.run({ input: upload.file_id });

for (const chunk of result.result.chunks) {
  console.log(chunk.content);
}

package main

import (
    "context"
    "fmt"
    "io"
    "os"

    reducto "github.com/reductoai/reducto-go-sdk"
    "github.com/reductoai/reducto-go-sdk/option"
    "github.com/reductoai/reducto-go-sdk/shared"
)

func main() {
    client := reducto.NewClient(option.WithAPIKey(os.Getenv("REDUCTO_API_KEY")))

    file, _ := os.Open("invoice.pdf")
    defer file.Close()
    upload, _ := client.Upload(context.Background(), reducto.UploadParams{
        File: reducto.F[io.Reader](file),
    })

    result, _ := client.Parse.Run(context.Background(), reducto.ParseRunParams{
        ParseConfig: reducto.ParseConfigParam{
            DocumentURL: reducto.F[reducto.ParseConfigDocumentURLUnionParam](
                shared.UnionString(upload.FileID),
            ),
        },
    })

    if result.Result.Type == shared.ParseResponseResultTypeFull {
        chunks := result.Result.Chunks.([]shared.ParseResponseResultFullResultChunk)
        for _, chunk := range chunks {
            fmt.Println(chunk.Content)
        }
    }
}

# Upload
FILE_ID=$(curl -s -X POST https://platform.reducto.ai/upload \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -F "file=@invoice.pdf" | jq -r '.file_id')

# Parse
curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"input\": \"$FILE_ID\"}"

What You Get Back

{
  "job_id": "7600c8c5-a52f-49d2-8a7d-d75d1b51e141",
  "duration": 3.89,
  "result": {
    "type": "full",
    "chunks": [
      {
        "content": "# Invoice\n\nBill To: Acme Corp\n123 Main St...",
        "embed": "# Invoice\n\nBill To: Acme Corp...",
        "blocks": [
          {
            "type": "Title",
            "content": "Invoice",
            "bbox": { "left": 0.1, "top": 0.05, "width": 0.3, "height": 0.04, "page": 1 },
            "confidence": "high"
          }
        ]
      }
    ]
  },
  "usage": { "num_pages": 1, "credits": 2.0 },
  "studio_link": "https://studio.reducto.ai/job/7600c8c5-..."
}

Key fields:

Field	What it is
`chunks[].content`	The extracted content, formatted as Markdown (headers become `#`, tables become Markdown/HTML tables). Ready to pass to an LLM.
`chunks[].embed`	Same content but optimized for embeddings. When figure/table summaries are enabled, this field contains natural language descriptions instead of raw table markup.
`chunks[].blocks`	The individual elements (paragraphs, tables, figures) with their positions and types. Useful for highlighting or linking back to source.
`result.type`	Either `"full"` (content inline) or `"url"` (content at a URL). Large documents return `"url"` to avoid HTTP size limits.

Response Format Details

Full breakdown of chunks, blocks, bounding boxes, and confidence scores.

Input Options

The input field accepts four formats:

Upload response (reducto://...): After uploading via /upload, use the returned file_id. This is the most common method for local files.
Public URL: Any publicly accessible URL. Reducto fetches the file directly.
Presigned URL: S3, GCS, or Azure Blob presigned URLs work. Useful when files are in your cloud storage.
Previous job ID (jobid://...): Reprocess a document from a previous parse job without re-uploading. Useful for testing different configurations.

# From upload
result = client.parse.run(input=upload.file_id)

# Public URL
result = client.parse.run(input="https://example.com/doc.pdf")

# Presigned S3 URL  
result = client.parse.run(input="https://bucket.s3.amazonaws.com/doc.pdf?X-Amz-...")

# Reprocess previous job
result = client.parse.run(input="jobid://7600c8c5-a52f-49d2-8a7d-d75d1b51e141")

// From upload
const result = await client.parse.run({ input: upload.file_id });

// Public URL
const result = await client.parse.run({ input: 'https://example.com/doc.pdf' });

// Presigned S3 URL
const result = await client.parse.run({ input: 'https://bucket.s3.amazonaws.com/doc.pdf?X-Amz-...' });

// Reprocess previous job
const result = await client.parse.run({ input: 'jobid://7600c8c5-a52f-49d2-8a7d-d75d1b51e141' });

// From upload
result, _ := client.Parse.Run(context.Background(), reducto.ParseRunParams{
    ParseConfig: reducto.ParseConfigParam{
        DocumentURL: reducto.F[reducto.ParseConfigDocumentURLUnionParam](
            shared.UnionString(upload.FileID),
        ),
    },
})

// Public URL
result, _ := client.Parse.Run(context.Background(), reducto.ParseRunParams{
    ParseConfig: reducto.ParseConfigParam{
        DocumentURL: reducto.F[reducto.ParseConfigDocumentURLUnionParam](
            shared.UnionString("https://example.com/doc.pdf"),
        ),
    },
})

# From upload
curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "reducto://your-file-id"}'

# Public URL
curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "https://example.com/doc.pdf"}'

# Reprocess previous job
curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "jobid://7600c8c5-a52f-49d2-8a7d-d75d1b51e141"}'

Sync vs Async

Parse has both synchronous (/parse) and asynchronous (/parse_async) endpoints. Use async for large documents or when you need webhook delivery.

Sync vs Async Guide

When to use each, how priority works, webhook setup.

Configuration

Parse has several configuration groups. Here are the most commonly changed options:

Chunking

By default, Parse returns the entire document as one chunk. For RAG applications, you want smaller chunks that can be embedded and retrieved independently.

result = client.parse.run(
    input=upload.file_id,
    retrieval={
        "chunking": {"chunk_mode": "variable"}
    }
)

const result = await client.parse.run({
  input: upload.file_id,
  retrieval: {
    chunking: { chunk_mode: 'variable' }
  }
});

result, _ := client.Parse.Run(context.Background(), reducto.ParseRunParams{
    ParseConfig: reducto.ParseConfigParam{
        DocumentURL: reducto.F[reducto.ParseConfigDocumentURLUnionParam](
            shared.UnionString(upload.FileID),
        ),
    },
    Retrieval: reducto.F(reducto.RetrievalParam{
        Chunking: reducto.F(reducto.RetrievalChunkingUnionParam{
            OfVariableChunking: &reducto.VariableChunkingConfigParam{
                ChunkMode: reducto.F(reducto.VariableChunkingConfigChunkModeVariable),
            },
        }),
    }),
})

curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "reducto://your-file-id",
    "retrieval": {
      "chunking": {"chunk_mode": "variable"}
    }
  }'

Mode	Behavior
`disabled`	One chunk for the whole document (default)
`variable`	Splits at semantic boundaries (sections, tables, figures stay intact). Best for RAG.
`page`	One chunk per page
`section`	Splits at section headers

Full chunking options →

Table Output Format

Controls how tables appear in the output.

result = client.parse.run(
    input=upload.file_id,
    formatting={
        "table_output_format": "html"
    }
)

const result = await client.parse.run({
  input: upload.file_id,
  formatting: {
    table_output_format: 'html'
  }
});

result, _ := client.Parse.Run(context.Background(), reducto.ParseRunParams{
    ParseConfig: reducto.ParseConfigParam{
        DocumentURL: reducto.F[reducto.ParseConfigDocumentURLUnionParam](
            shared.UnionString(upload.FileID),
        ),
    },
    Formatting: reducto.F(reducto.FormattingParam{
        TableOutputFormat: reducto.F(reducto.FormattingTableOutputFormatHTML),
    }),
})

curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "reducto://your-file-id",
    "formatting": {
      "table_output_format": "html"
    }
  }'

Format	When to use
`dynamic`	Auto-selects HTML or Markdown based on table complexity (default)
`html`	Complex tables with merged cells, nested headers
`md`	Simple tables, Markdown-based workflows
`json`	Programmatic processing, need cell-level access
`csv`	Export to spreadsheets

Full table format options →

Figure Summaries

r-1 detects figures and generates a short description as part of the same full-page pass. When your workflow needs a specific interpretation, add a figure-scoped custom prompt. Reducto runs the specialized figure model for relevant figures. This adds latency.

result = client.parse.run(
    input=upload.file_id,
    enhance={
        "agentic": [
            {
                "scope": "figure",
                "prompt": "Describe the relationships between components in this diagram."
            }
        ]
    }
)

const result = await client.parse.run({
  input: upload.file_id,
  enhance: {
    agentic: [
      {
        scope: "figure",
        prompt: "Describe the relationships between components in this diagram."
      }
    ]
  }
});

curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "reducto://your-file-id",
    "enhance": {
      "agentic": [
        {
          "scope": "figure",
          "prompt": "Describe the relationships between components in this diagram."
        }
      ]
    }
  }'

Agentic Mode

r-1 handles difficult text, tables, figures, and page layouts. It is not necessary to enable agentic mode as a general accuracy upgrade. Use agentic mode when you need one or more custom prompts that change how Reducto interprets content for your workflow. For example, a table prompt can specify how to encode domain-specific content in the parsed output.

result = client.parse.run(
    input=upload.file_id,
    enhance={
        "agentic": [
            {
                "scope": "table",
                "prompt": "Preserve domain-specific notation such as <0.01, ±, and N/A exactly as written."
            }
        ]
    }
)

const result = await client.parse.run({
  input: upload.file_id,
  enhance: {
    agentic: [
      {
        scope: "table",
        prompt: "Preserve domain-specific notation such as <0.01, ±, and N/A exactly as written."
      }
    ]
  }
});

curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "reducto://your-file-id",
    "enhance": {
      "agentic": [
        {
          "scope": "table",
          "prompt": "Preserve domain-specific notation such as <0.01, ±, and N/A exactly as written."
        }
      ]
    }
  }'

The agentic array can include custom prompts for more than one supported scope. Pages that need a custom prompt run through the matching agentic pipeline, while other pages continue through r-1. Agentic processing adds latency. For structured numerical data from charts, add advanced chart extraction to a figure-scoped agentic configuration. Reducto runs the separate chart extraction agent and augments the r-1 result.

Filter Blocks

Remove specific content types from the output. The blocks still appear in blocks metadata but are excluded from content and embed.

result = client.parse.run(
    input=upload.file_id,
    retrieval={
        "filter_blocks": ["Header", "Footer", "Page Number"]
    }
)

const result = await client.parse.run({
  input: upload.file_id,
  retrieval: {
    filter_blocks: ['Header', 'Footer', 'Page Number']
  }
});

result, _ := client.Parse.Run(context.Background(), reducto.ParseRunParams{
    ParseConfig: reducto.ParseConfigParam{
        DocumentURL: reducto.F[reducto.ParseConfigDocumentURLUnionParam](
            shared.UnionString(upload.FileID),
        ),
    },
    Retrieval: reducto.F(reducto.RetrievalParam{
        FilterBlocks: reducto.F([]reducto.RetrievalFilterBlock{
            reducto.RetrievalFilterBlockHeader,
            reducto.RetrievalFilterBlockFooter,
            reducto.RetrievalFilterBlockPageNumber,
        }),
    }),
})

curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "reducto://your-file-id",
    "retrieval": {
      "filter_blocks": ["Header", "Footer", "Page Number"]
    }
  }'

Useful for RAG when headers/footers would pollute search results.

Page Range

Process only specific pages.

result = client.parse.run(
    input=upload.file_id,
    settings={
        "page_range": {"start": 1, "end": 10}
    }
)

const result = await client.parse.run({
  input: upload.file_id,
  settings: {
    page_range: { start: 1, end: 10 }
  }
});

result, _ := client.Parse.Run(context.Background(), reducto.ParseRunParams{
    ParseConfig: reducto.ParseConfigParam{
        DocumentURL: reducto.F[reducto.ParseConfigDocumentURLUnionParam](
            shared.UnionString(upload.FileID),
        ),
    },
    Settings: reducto.F(reducto.SettingsParam{
        PageRange: reducto.F(reducto.PageRangeParam{
            Start: reducto.F(int64(1)),
            End:   reducto.F(int64(10)),
        }),
    }),
})

curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "reducto://your-file-id",
    "settings": {
      "page_range": {"start": 1, "end": 10}
    }
  }'

Return Images

Get image URLs for figures and tables in the document.

result = client.parse.run(
    input=upload.file_id,
    settings={
        "return_images": ["figure", "table"]
    }
)

# Access images from blocks
for chunk in result.result.chunks:
    for block in chunk.blocks:
        if block.image_url:
            print(f"{block.type}: {block.image_url}")

const result = await client.parse.run({
  input: upload.file_id,
  settings: {
    return_images: ['figure', 'table']
  }
});

// Access images from blocks
for (const chunk of result.result.chunks) {
  for (const block of chunk.blocks) {
    if (block.image_url) {
      console.log(`${block.type}: ${block.image_url}`);
    }
  }
}

curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "reducto://your-file-id",
    "settings": {
      "return_images": ["figure", "table"]
    }
  }'

Options: ["figure"], ["table"], or ["figure", "table"]. By default, no images are returned.

Additional Settings

Setting	Default	Description
`persist_results`	`false`	Keep results indefinitely instead of expiring after 24 hours
`timeout`	`null`	Custom timeout in seconds for processing
`force_url_result`	`false`	Always return results as a URL (useful for consistent handling)
`embed_pdf_metadata`	`false`	Embed OCR metadata into returned PDF
`extract_document_properties`	`false`	Return properties embedded in the original pre-conversion document

Set extract_document_properties to true to include a top-level document_properties object in the response. The setting defaults to false and reads metadata from the original file before conversion.

result = client.parse.run(
    input=upload.file_id,
    settings={"extract_document_properties": True}
)

const result = await client.parse.run({
  input: upload.file_id,
  settings: { extract_document_properties: true }
});

curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "reducto://your-file-id",
    "settings": {"extract_document_properties": true}
  }'

The response includes document_properties for supported files with embedded properties. It is null when no properties are found or the input format is unsupported. Supported formats are PDF, DOCX, XLSX, and PPTX. Legacy binary .doc, .xls, and .ppt files are not supported. All fields are nullable, and dates use timezone-aware ISO-8601 strings. PDF Info/XMP populates title, author, subject, keywords, creator, producer, created_at, and modified_at. last_modified_by is only available from OOXML core properties. DOCX, XLSX, and PPTX can populate title, author, subject, keywords, creator, last_modified_by, created_at, and modified_at; producer is PDF-only.

{
  "document_properties": {
    "title": "Quarterly Report",
    "author": "Jane Smith",
    "subject": "Financial results",
    "keywords": "finance, quarterly",
    "creator": "Microsoft Word",
    "producer": null,
    "last_modified_by": "Alex Chen",
    "created_at": "2024-01-15T09:30:00+00:00",
    "modified_at": "2024-02-01T16:45:12+00:00"
  }
}

result = client.parse.run(
    input=upload.file_id,
    settings={
        "persist_results": True,
        "timeout": 120,
        "force_url_result": True
    }
)

For complete configuration reference including legacy OCR settings, spreadsheet options, and more, see the Configuration section.

Troubleshooting

Tables look wrong

Try formatting.table_output_format: "html". HTML handles merged cells and complex headers better than Markdown.Still broken? Add a table-scoped custom prompt that describes how Reducto should represent the table for your use case.

Response is slow

Main causes:

Customized agentic processing adds latency
On legacy Parse, enhance.summarize_figures adds latency for documents with figures
Large documents take longer linearly
async_priority should be True for faster priority processing

For fastest processing, disable what you don’t need. See Best Practices.

Password-protected PDF

result = client.parse.run(
    input=upload.file_id,
    settings={"document_password": "your-password"}
)

const result = await client.parse.run({
  input: upload.file_id,
  settings: { document_password: 'your-password' }
});

curl -X POST https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "reducto://your-file-id",
    "settings": {"document_password": "your-password"}
  }'

Response is a URL instead of content

Large documents return result.type: "url" instead of inline content to avoid HTTP size limits. Fetch the content:

import requests

if result.result.type == "url":
    chunks = requests.get(result.result.url).json()
else:
    chunks = result.result.chunks

let chunks;
if (result.result.type === 'url') {
  const response = await fetch(result.result.url);
  chunks = await response.json();
} else {
  chunks = result.result.chunks;
}

# If result.type is "url", fetch from the URL
curl -s "$RESULT_URL" | jq '.chunks'

To always get a URL (consistent handling): settings.force_url_result: true

Next Steps

Response Format

Full breakdown of chunks, blocks, and bounding boxes.

Best Practices

Optimization by document type, latency tips.

Choosing a parser for RAG

Reading order, tables, layout-aware chunks, and citations compared across parsers.

Comparing parsing accuracy

Which metrics to compare for character recognition, layout, and table extraction.

Get Started

Developer Tools

Core Functions

Workflows and Pipelines

Configurations

Reference

Components

Enterprise Resources

Security and privacy

On-premise Resources

Parse overview

Choose a Parse pipeline

Quick Start

What You Get Back

Response Format Details

Input Options

Sync vs Async

Sync vs Async Guide

Configuration

Chunking

Table Output Format

Figure Summaries

Agentic Mode

Filter Blocks

Page Range

Return Images

Additional Settings

Troubleshooting

Next Steps

Response Format

Best Practices

Choosing a parser for RAG

Comparing parsing accuracy

​Choose a Parse pipeline

​Quick Start

​What You Get Back

Response Format Details

​Input Options

​Sync vs Async

Sync vs Async Guide

​Configuration

​Chunking

​Table Output Format

​Figure Summaries

​Agentic Mode

​Filter Blocks

​Page Range

​Return Images

​Additional Settings

​Troubleshooting

​Next Steps

Response Format

Best Practices

Choosing a parser for RAG

Comparing parsing accuracy

Choose a Parse pipeline

Quick Start

What You Get Back

Input Options

Sync vs Async

Configuration

Chunking

Table Output Format

Figure Summaries

Agentic Mode

Filter Blocks

Page Range

Return Images

Additional Settings

Troubleshooting

Next Steps