Parse Document
Upload a document for parsing and retrieve ordered Markdown chunks with layout metadata.
Overview
The Parse Document endpoint processes PDFs, images (PNG, JPEG, TIFF, WebP), presentations (PPT, PPTX), word-processing files (DOC, DOCX), and HTML files (HTML, HTM). It breaks each document into sections with text, images, tables, and optical character recognition (OCR) data. You can provide a document by direct file upload or by URL. The parse endpoint uploads your document and configuration in a single request:- POST to
/parsewith your file and configuration: the API uploads the document and creates a parse job. - The job is automatically enqueued for processing.
- Poll
GET /parse/{job_id}to track progress and retrieve results.
Request
file or url. If both are provided, file takes precedence.url is not provided. Use POST /parse/excel for XLS and XLSX workbooks.file is not provided.fast (Fast), agentic_lite (Agentic Lite), or agentic (Agentic). Each mode applies a recommended processing configuration that trades speed for fidelity. Parameters you send explicitly take precedence over the mode. See Processing Modes to choose one. Omit to use the default configuration.false.false.false.["Table", "Formula", "Picture"]. Defaults to ["Table", "Picture"]; an empty or unparseable value also falls back to that default, so Table and Picture validation runs even when this field is omitted."all" to include everything. Defaults to "all".Available segment types:table: Tabular data segmentspicture: Image and graphic segmentsformula: Mathematical equationstext: Regular text contentsectionheader: Section headerstitle: Document titleslistitem: List itemscaption: Image captionsfootnote: Footnotespageheader: Page headerspagefooter: Page footerskeyvaluepair: Key-value pairs (Agentic Lite and Agentic modes)page: Full-page segments
"table", "table,picture", "table,formula", "picture,formula".false."basic"(default): no chart data. Picture segments keep their usual description."standard": fast and accurate chart data extraction."advanced": for the most complex and messiest charts. Contact support to have this feature enabled for your organization; until it is, a request withadvancedreturns403witherror.codeset tofeature_not_enabled.
chart_data includes chart_type, chart_title, x_label, y_label, legend, confidence, metadata, and data: an object keyed by series name, each series a list of {"x": ..., "y": ...} points. It is attached only when the chart’s values were recovered; when it is, the segment’s markdown and html show the chart’s data as a summary and one table per series. Otherwise the segment keeps its description and has no chart_data.The Agentic (agentic) processing mode uses standard unless you set this field.false to exclude them and reduce response size. All fields default to true.Available fields:html: HTML representation of segmentsmarkdown: Markdown representation of segmentsocr: Raw OCR text data with bounding boxes and confidence scoresimage: Cropped segment images (base64 encoded)content: Text content of segmentsbbox: Bounding box coordinatesconfidence: Confidence scores for segmentsembed: Vector embeddings / embed textchart_data: Extracted chart data for Picture segments identified as charts
{"html": true, "markdown": true, "ocr": false, "image": false}.html:"VLM"or"Auto"markdown:"VLM"or"Auto"vlm: Custom prompt for the VLM model. Use this to give the model specific instructions for extracting or describing these segment types.
html and markdown are not uniform across segment types. Table.html, Picture.markdown, Formula.markdown, KeyValuePair.markdown, and both Page strategies default to "VLM"; everything else defaults to "Auto". See Segment Analysis Configuration below for the full table and override examples.["docx"]. When set, the pipeline generates the requested export files after parsing completes. The exported files are available as presigned URLs in the exports field of the response. Supported values: "docx", "markdown", "json".["docx"]), not a repeated field. Passing a bare value like docx will fail to parse and silently skip the export."Continue" (default) proceeds despite errors (e.g., LLM refusals on individual segments). "Fail" stops and fails the task on any error.POST /parse — the task is not auto-deleted. To get a presigned-upload TTL, use POST /v2/parse/upload instead, where expires_in controls the upload URL’s validity.Configuration Best Practices
High-Accuracy Processing
High-Accuracy Processing
- Legal documents requiring precise text extraction
- Financial statements with complex tables
- Archival documents with low-quality scans
- Documents where accuracy is more important than speed
- Latency: the Agentic mode re-reads every segment, so jobs take longer
- Latency: +1-2 seconds per page for segment validation
Fast Processing
Fast Processing
- High-volume document processing
- Real-time applications requiring quick results
- Documents with simple layouts
- Pre-screened high-quality digital documents
- Fastest processing time
- Lower cost per document
- Suitable for batch processing large volumes
Financial Documents (Tables + Charts)
Financial Documents (Tables + Charts)
- Balance sheets and P&L statements
- Quarterly/annual financial reports
- Investment reports with charts
- Documents where only structured data matters
- Reduced response size (text content filtered out)
- Focus on data-rich content
- Merged multi-page tables for complete datasets
Data Extraction Only (Tables)
Data Extraction Only (Tables)
- Extracting data from invoices
- Processing structured forms
- Database population from documents
- CSV/Excel export workflows
- Minimal response payload
- Faster data transfer
- Easy integration with data pipelines
Academic/Research Documents
Academic/Research Documents
- Research papers with bibliographies
- Academic articles with citations
- Scientific documents
- Literature reviews
- Automatic citation extraction and linking
- Structured bibliography metadata
- In-text citation hyperlinks in markdown
- Preserves academic document structure
Scanned Documents
Scanned Documents
- Scanned paper documents
- Low-quality photocopies
- Historical documents
- Image-based PDFs
- Maximum OCR coverage
- Better text extraction from poor quality sources
- Higher accuracy for challenging documents
Output Fields Optimization
Output Fields Optimization
output_fields or set all fields to True to include all available data.Benefits:- Reduced response size and bandwidth usage
- Faster processing and data transfer
- Cost optimization for high-volume processing
Parameter Details
File Input Options
The API supports two methods for providing the document to process:- Direct File Upload (
fileparameter): Upload the document file directly as multipart/form-data - Presigned URL (
urlparameter): Provide a publicly accessible URL or presigned URL to the document
- You must provide either
fileorurl, but not both - When using
url, the document will be downloaded from the provided URL before processing - Presigned URLs are ideal for documents already stored in cloud storage (S3, GCS, Azure Blob, etc.)
- The URL must be publicly accessible or include necessary authentication parameters (e.g., S3 presigned URLs with signatures)
- Supported formats are the same for both methods: PDF, images (PNG, JPEG, TIFF, WebP), presentations (PPT, PPTX), word-processing files (DOC, DOCX), and HTML files (HTML, HTM). Use
POST /parse/excelfor XLS and XLSX workbooks.
- Documents already stored in cloud storage
- Avoiding duplicate file uploads
- Integration with existing document management systems
- Processing documents already available at a URL without uploading them again
Table Merging
Themerge_tables parameter enables merging of tables that span across multiple pages:
How It Works:
- Analyzes consecutive table segments across pages
- Identifies tables with matching column headers
- Merges them into a single unified table structure
- Preserves table formatting and data integrity
- Multi-Page Financial Statements: Consolidate P&L statements or balance sheets spanning multiple pages
- Large Data Tables: Merge inventory lists, transaction records, or data sets split across pages
- Reports with Continuation Tables: Automatically combine tables marked with “continued on next page”
- Simplified Data Processing: Work with complete tables instead of fragments
- Better Context: Maintain full table context for analysis and extraction
- Reduced Post-Processing: Eliminates need for manual table stitching
Citation Extraction (Research Papers)
xml_citation parameter enables automatic extraction and linking of citations from research papers, academic articles, and scientific documents.
How It Works:
- Extracts structured bibliography from the document
- Identifies in-text citation references (e.g., “Chen et al., 2021”)
- Hyperlinks citations in the markdown output to their bibliography entries
- Returns structured citation metadata in the response
metadata field with structured citation data:
- Original:
"As shown by Chen et al. (2021)..." - Enhanced:
"As shown by [Chen et al. (2021)](#ref-5)..."
Content Type Filtering
Thesegment_filter parameter allows you to filter the output to include only specific segment types, reducing response size and focusing on relevant content:
How It Works:
- Accepts a comma-separated list of segment types (case-insensitive)
- Filters segments after processing is complete
- Removes chunks that have no segments after filtering
"all"(default): Include all segment types"table": Only table segments"picture": Only image/graphic segments"table,picture": Tables and pictures only"table,formula": Tables and formulas only- Custom combinations using any segment type
table,picture,formula,text,sectionheader,title,listitem,caption,footnote,pageheader,pagefooter
- Tables Only: Extract only tabular data from financial documents
- Pictures Only: Extract charts, graphs, and diagrams for visual analysis
- Tables + Pictures: Get structured data and visualizations, skip text content
- Custom Combinations: Mix any segment types based on your needs
- Reduced Response Size: Filter out unwanted content before receiving results
- Faster Processing: Less data to transfer and parse
- Focused Extraction: Get only the content types you need
- Cost Optimization: Smaller responses reduce bandwidth usage
Output Fields Configuration
Theoutput_fields parameter allows you to control which fields are included in the API response. This is useful for reducing response size, improving performance, and optimizing bandwidth usage when you don’t need all available data.
Available Fields:
html(default:true): Include HTML representation of segmentsmarkdown(default:true): Include Markdown representation of segmentsocr(default:true): Include OCR results with bounding boxes and confidence scoresimage(default:true): Include cropped segment images (base64 encoded)content(default:true): Include text content of segmentsbbox(default:true): Include bounding box coordinatesconfidence(default:true): Include confidence scores for segmentsembed(default:true): Include embed text in chunk responses
false to exclude them from the response. Fields not specified default to true for backward compatibility.
Example Configuration:
- Reduced Response Size: Excluding large fields like
imageandhtmlcan significantly reduce payload size - Faster Processing: Less data to serialize and transfer
- Cost Optimization: Smaller responses reduce bandwidth costs
- Selective Data: Only retrieve the fields you need for your use case
- Minimal Response: Set most fields to
falsewhen you only need basic content - Text-Only Processing: Exclude
imageandocrwhen processing text content - Embedding Generation: Include only
contentandembedwhen generating embeddings - Full Analysis: Keep all fields enabled (default) for comprehensive document analysis
Segment Analysis Configuration
Thesegment_analysis parameter allows you to customize how different segment types are processed, including HTML/Markdown generation strategies and custom VLM prompts.
Available Segment Types:
You can configure processing for any of the following segment types:
Table: Tabular data segmentsPicture: Image and graphic segmentsFormula: Mathematical equationsTitle: Document titlesSectionHeader: Section headersText: Regular text contentListItem: List itemsCaption: Image captionsFootnote: FootnotesPageHeader: Page headersPageFooter: Page footersPage: Full page segmentsKeyValuePair: Form field regions (labels with their filled-in values). Only produced for form documents; the config is accepted either way.
-
html: Generation strategy for HTML representation"Auto": Build HTML directly from the OCR/recognized text (skips the VLM call — faster and cheaper)"VLM": Use a VLM to generate HTML
-
markdown: Generation strategy for Markdown representation"Auto": Build Markdown directly from the OCR/recognized text (skips the VLM call — faster and cheaper)"VLM": Use a VLM to generate Markdown
KeyValuePairkeeps each label with its value in one segment, checkbox and radio state included. It also carries animagecrop URL when you poll withinclude_url=true. -
vlm: Custom prompt for the VLM model. Use this to give the model specific instructions for extracting or describing these segment types.
- VLM-Enhanced Output: Use
"VLM"for bothhtmlandmarkdowngeneration strategies to get AI-enhanced representations in those fields - Custom Instructions: Use
vlmto tell the model how to read a segment type, for example how to treat merged cells in tables
Response
"unknown" when no usable segment exists.merge_tables value).Document Analysis Features
The parsing endpoint provides comprehensive document analysis including:Text Extraction
Extracts text content with high accuracy, preserving formatting and structure.Image Recognition
Identifies and analyzes images within documents, providing descriptions and metadata.Table Parsing
Extracts tabular data with proper structure and formatting.OCR Processing
Performs optical character recognition on text elements with confidence scores.Section Detection
Automatically identifies different document sections like headers, body text, and captions.Bounding Box Information
Provides precise coordinates for all extracted elements.Advanced Content Processing
- VLM-Enhanced Analysis: Uses vision-language models for better content understanding
- Multi-Format Output: Generates HTML, Markdown, and plain text versions
- Context-Aware Processing: Maintains document context across segments
- Intelligent Chunking: Creates semantically meaningful document chunks
Retrieving Results
After the job is created, use the GET /parse/ endpoint to check status and retrieve results:Expected Results Structure
When the job completes successfully, the response contains comprehensive document analysis with enhanced processing:Segment Types
The parsing API identifies and processes different types of document segments with enhanced processing:Picture
Images and graphics within the document, including logos, charts, and illustrations. Enhanced with VLM-based description generation.SectionHeader
Document headers and titles that define section boundaries. Processed with semantic understanding.Text
Regular text content including paragraphs, sentences, and individual text elements. Enhanced with context-aware processing.Table
Tabular data with structured rows and columns. Enhanced with VLM-based formatting. The table reader is chosen by the processingmode; use vlm in the segment_analysis parameter to give it custom instructions.
Caption
Text captions associated with images or figures. Processed with relationship awareness.Formula
Mathematical equations and expressions. Enhanced with specialized formula processing.Title
Document titles and main headings. Processed with enhanced formatting.Footnote
Document footnotes and references. Processed with context linking.ListItem
Bulleted and numbered list items. Processed with structure preservation.KeyValuePair
Form field regions — a printed label together with the value filled in against it. Produced for form documents in the Agentic Lite and Agentic modes (mode=agentic_lite or mode=agentic). See Element Types for a full response sample.
Each segment includes detailed metadata such as confidence scores, bounding boxes, OCR data, and formatted output in both HTML and Markdown with VLM enhancement.
Error Handling
Common Error Scenarios
- Invalid API Key: Authentication failed
- File Too Large: File exceeds size limits
- Invalid Configuration: Malformed processing parameters
- Server Error: Internal processing error
- Processing Timeout: Task took too long to complete
- Missing File or URL: Neither
filenorurlparameter provided - Both File and URL Provided: Cannot provide both
fileandurlsimultaneously - Invalid URL: URL is not accessible or malformed
- URL Download Failed: Unable to download document from provided URL
- Insufficient Quota (
402): Not enough page credits remaining. - Usage Limit Exceeded (
429): Billing usage cap reached. Returns plain text:Usage limit exceeded. NoRetry-Afterheader. - Rate Limit Exceeded (
429): Org exceeded its per-second request budget (100 requests per second per organization by default; higher limits are available on request). Returns JSON{"error": "rate_limit_exceeded", "message": ..., "retry_after": 1}with aRetry-After: 1header. - Internal Server Error (
500): An unexpected error occurred during processing. - Service Unavailable (
503): Job queue is at capacity. Retry after the duration indicated in theRetry-Afterheader. - Forbidden (
403): Access has been revoked.
Authorizations
Body
Multipart form data. Provide either file (binary upload) or url (presigned/public URL), not both.
Request body for POST /parse (multipart/form-data).
Provide either file (binary upload) or url (presigned/public URL) — not both.
Export format(s) to generate after processing.
When set, the pipeline generates the requested export files after parsing completes.
The exported files are available as presigned URLs in the exports field of the response.
Supported: ["docx", "markdown", "json"].
docx, markdown, json Digitize charts into the numbers they were drawn from, attached to the Picture segment as chart_data. basic (default): no chart data. standard: fast and accurate chart data extraction. advanced: for the most complex and messiest charts; contact support to have it enabled for your organization (otherwise 403 with error.code = feature_not_enabled).
basic, standard, advanced Processing mode preset. fast (Fast), agentic_lite (Agentic Lite), or agentic (Agentic). Each mode applies a recommended processing configuration; see Processing Modes. Parameters you send explicitly take precedence over the mode. Omit to use the default configuration.
fast, agentic_lite, agentic Response
Job created — poll with GET /parse/{job_id} to retrieve results.
Response body for a successful POST /parse call.

