> This page is optimized for agents. Use the linked Markdown pages and llms.txt indexes for related API content.

# Async Parse

- Product: Reducto API
- Section: Parse
- Snapshot: Current
- Method: `POST`
- Path: `/parse_async`

## Request body

Required: yes  
Content types: `application/json`  

### `async`

Type: `config__v3__AsyncConfig`  
Required: no  

The configuration options for asynchronous processing (default synchronous).

#### `metadata`

Type: `unknown`  
Required: no  

JSON metadata included in webhook request body. Defaults to None.

#### `priority`

Type: `boolean`  
Required: no  
Default: `false`  

Workers poll the priority queue ahead of the standard queue, so priority jobs start sooner when there is queued work; sync jobs are prioritized above async jobs by default.

#### `webhook`

Type: `SvixWebhookConfig | DirectWebhookConfig`  
Required: no  

The webhook configuration for the asynchronous processing.

##### SvixWebhookConfig

Type: `SvixWebhookConfig`  

###### `mode`

Type: `string`  
Required: no  
Default: `svix`  

###### `channels`

Type: `string[]`  
Required: no  

A list of Svix channels the message will be delivered down, omit to send to all channels.

###### string

Type: `string`  

##### DirectWebhookConfig

Type: `DirectWebhookConfig`  

###### `mode`

Type: `string`  
Required: no  
Default: `direct`  

###### `url`

Type: `string`  
Required: yes  

##### unknown

Type: `unknown`  

### `input`

Type: `string | string[] | UploadResponse`  
Required: yes  

For parse/split/extract pipelines, the URL of the document to be processed. You can provide one of the following:
            1. A publicly available URL
            2. A presigned S3 URL
            3. A reducto:// prefixed URL obtained from the /upload endpoint after directly uploading a document
            4. A jobid:// prefixed URL obtained from a previous /parse invocation
            5. A list of URLs (for multi-document pipelines, V3 API only)

            For edit pipelines, this should be a string containing the edit instructions

#### string

Type: `string`  

#### string[]

Type: `string[]`  

##### string

Type: `string`  

#### UploadResponse

Type: `UploadResponse`  

##### `file_id`

Type: `string`  
Required: yes  

##### `presigned_url`

Type: `string`  
Required: no  

###### string

Type: `string`  

###### unknown

Type: `unknown`  

### `enhance`

Type: `Enhance`  
Required: no  

#### `agentic`

Type: `one of 3[]`  
Required: no  

For legacy Parse, agentic processing uses vision language models to improve text, table, or figure extraction. With r-1, use agentic processing for custom prompts or advanced chart extraction. Agentic processing adds latency.

##### one of 3

Type: `one of 3`  

###### TableAgentic

Type: `TableAgentic`  

###### `scope`

Type: `string`  
Required: yes  

###### `prompt`

Type: `string`  
Required: no  

Custom prompt for table agentic.

###### string

Type: `string`  

###### unknown

Type: `unknown`  

###### `mode`

Type: `string`  
Required: no  
Allowed values: `default`, `auto`, `max`  
Default: `default`  

Mode for table agentic: 'default' selectively applies enrichment only to tables likely to benefit, and 'max' runs enrichment on all tables.

###### FigureAgentic

Type: `FigureAgentic`  

###### `scope`

Type: `string`  
Required: yes  

###### `prompt`

Type: `string`  
Required: no  

Custom prompt for figure agentic.

###### string

Type: `string`  

###### unknown

Type: `unknown`  

###### `advanced_chart_agent`

Type: `boolean`  
Required: no  
Default: `false`  

If True, run advanced chart extraction on figures classified as charts: an agentic extractor that returns full structured series data (chart_data) plus a reconstruction image re-drawn from that data (extra.chart_reconstruction). Higher latency. Defaults to False.

###### TextAgentic

Type: `TextAgentic`  

###### `scope`

Type: `string`  
Required: yes  

###### `prompt`

Type: `string`  
Required: no  

Custom instructions for agentic text. Note: This only applies to form regions (key-value).

###### string

Type: `string`  

###### unknown

Type: `unknown`  

#### `advanced_chart_agent`

Type: `boolean`  
Required: no  
Default: `false`  

If True, run advanced chart extraction on figures classified as charts, without requiring a figure-scoped agentic entry. Returns full structured series data (chart_data) plus a reconstruction image re-drawn from that data. Higher latency. Defaults to False.

#### `summarize_figures`

Type: `boolean`  
Required: no  
Default: `true`  

For legacy Parse, if True, summarize figures using a separate vision language model. r-1 generates figure descriptions natively and ignores this setting. Defaults to True.

#### `intelligent_ordering`

Type: `boolean`  
Required: no  
Default: `false`  

For legacy Parse, if True, use an advanced vision language model to improve reading order accuracy, with a small increase in latency. r-1 handles reading order natively and ignores this setting. Defaults to False.

### `retrieval`

Type: `Retrieval`  
Required: no  

#### `chunking`

Type: `Chunking`  
Required: no  

##### `chunk_mode`

Type: `string`  
Required: no  
Allowed values: `variable`, `section`, `page`, `disabled`, `block`, `page_sections`  
Default: `disabled`  

Choose how to partition chunks. Variable mode chunks by character length and visual context. Section mode chunks by section headers. Page mode chunks according to pages. Page sections mode chunks first by page, then by sections within each page. Disabled returns one single chunk.

##### `chunk_size`

Type: `number`  
Required: no  

The approximate size of chunks (in characters) that the document will be split into. Defaults to null, in which case the chunk size is variable between 250 - 1500 characters.

###### number

Type: `number`  

###### unknown

Type: `unknown`  

##### `chunk_overlap`

Type: `number`  
Required: no  
Default: `0`  

Number of characters of overlap to include from adjacent chunks. Defaults to 0.

#### `filter_blocks`

Type: `string[]`  
Required: no  

A list of block types to filter out from 'content' and 'embed' fields. By default, no blocks are filtered.

##### string

Type: `string`  
Allowed values: `Header`, `Footer`, `Title`, `Section Header`, `Page Number`, `List Item`, `Figure`, `Table`, `Key Value`, `Text`, `Comment`, `Signature`  

#### `embedding_optimized`

Type: `boolean`  
Required: no  
Default: `false`  

If True, use embedding optimized mode. Defaults to False.

### `formatting`

Type: `Formatting`  
Required: no  

#### `add_page_markers`

Type: `boolean`  
Required: no  
Default: `false`  

If True, add page markers to the output. Defaults to False. Useful for extracting data with page specific information.

#### `table_output_format`

Type: `string`  
Required: no  
Allowed values: `html`, `json`, `md`, `jsonbbox`, `dynamic`, `csv`  
Default: `dynamic`  

The table output format. Defaults to dynamic, which returns md for simpler tables and html for more complex tables. r-1 does not support jsonbbox.

#### `merge_tables`

Type: `boolean`  
Required: no  
Default: `false`  

A flag to indicate if consecutive tables with the same number of columns should be merged. Defaults to False.

#### `include`

Type: `string[]`  
Required: no  

For legacy Parse, the formatting details to include in the output. r-1 always includes highlights, signatures, hyperlinks, and watermark removal, and ignores those values.

##### string

Type: `string`  
Allowed values: `change_tracking`, `highlight`, `comments`, `hyperlinks`, `signatures`, `ignore_watermarks`  

### `spreadsheet`

Type: `Spreadsheet`  
Required: no  

#### `split_large_tables`

Type: `SplitLargeTables`  
Required: no  

##### `enabled`

Type: `boolean`  
Required: no  
Default: `true`  

If True, split large tables into smaller tables. Defaults to True.

##### `size`

Type: `number | SplitLargeTableSizes`  
Required: no  
Default: `50`  

The size of the tables to split into. Defaults to 50. Use 'row' and 'column' to independently specify the number of rows and columns to include when splitting. If you only want to split by rows or columns, set the other value to None.

###### number

Type: `number`  

###### SplitLargeTableSizes

Type: `SplitLargeTableSizes`  

###### `row`

Type: `number`  
Required: no  

The number of rows to include in each chunk when splitting large tables. Does not chunk rows if set to None.

###### number

Type: `number`  

###### unknown

Type: `unknown`  

###### `column`

Type: `number`  
Required: no  

The number of columns to include in each chunk when splitting large tables. Does not chunk columns if set to None.

###### number

Type: `number`  

###### unknown

Type: `unknown`  

#### `include`

Type: `string[]`  
Required: no  

Whether to include cell color, formula, and dropdown information in the output.

##### string

Type: `string`  
Allowed values: `cell_colors`, `formula`, `dropdowns`  

#### `clustering`

Type: `string`  
Required: no  
Allowed values: `accurate`, `fast`, `disabled`  
Default: `accurate`  

In a spreadsheet with different tables inside, we enable splitting up the tables by default. Accurate mode applies more powerful models for superior accuracy, at 5× the default per-cell rate. Disabling will register as one large table.

#### `exclude`

Type: `string[]`  
Required: no  

Whether to exclude hidden sheets, rows, or columns in the output.

##### string

Type: `string`  
Allowed values: `hidden_sheets`, `hidden_rows`, `hidden_cols`, `styling`, `spreadsheet_images`  

#### `max_cell_count`

Type: `number`  
Required: no  

Maximum total non-empty cells allowed across all sheets. If exceeded, the request is rejected with a 422 error. Set to null to disable the limit. Defaults to null.

##### number

Type: `number`  

##### unknown

Type: `unknown`  

### `settings`

Type: `Settings`  
Required: no  

#### `model`

Type: `string`  
Required: no  

The parse model to use. 'r-1' is the full-featured flagship model, with the highest accuracy and lower latency. 'r-1-mini' gives high accuracy at low cost. Both models include agentic capabilities for complex documents. 'r-1-mini' does not accept spreadsheets. 'legacy' is the previous parsing pipeline. Starting December 7, 2026, Parse defaults to 'r-1'. To keep legacy Parse, set this field to 'legacy'.

##### string

Type: `string`  
Allowed values: `r-1`, `r-1-mini`, `legacy`  

##### unknown

Type: `unknown`  

#### `ocr_system`

Type: `string`  
Required: no  
Allowed values: `standard`, `legacy`  
Default: `standard`  

The OCR system for legacy Parse. Standard is the best multilingual OCR system. Legacy supports Germanic languages and remains available for backwards compatibility. r-1 uses native full-page processing and ignores this setting. Defaults to standard.

#### `extraction_mode`

Type: `string`  
Required: no  
Allowed values: `ocr`, `hybrid`  
Default: `hybrid`  

The text extraction method for legacy Parse. OCR uses optical character recognition only. Hybrid combines OCR with embedded PDF text. r-1 uses native full-page processing and ignores this setting. Defaults to hybrid.

#### `force_url_result`

Type: `boolean`  
Required: no  
Default: `false`  

Force the result to be returned in URL form.

#### `force_file_extension`

Type: `string`  
Required: no  

Force the URL to be downloaded as a specific file extension (e.g. `.png`).

##### string

Type: `string`  

##### unknown

Type: `unknown`  

#### `return_ocr_data`

Type: `boolean`  
Required: no  
Default: `false`  

If True, return OCR data in the result. Defaults to False.

#### `return_images`

Type: `string[]`  
Required: no  

Whether to return images for the specified block types. 'page' returns full page images. By default, no images are returned.

##### string

Type: `string`  
Allowed values: `figure`, `table`, `page`  

#### `embed_pdf_metadata`

Type: `boolean`  
Required: no  
Default: `false`  

If True, embed OCR metadata into the returned PDF. Defaults to False.

#### `extract_document_properties`

Type: `boolean`  
Required: no  
Default: `false`  

If True, return properties embedded in the original document. Defaults to False.

#### `embed_pdf_metadata_dpi`

Type: `number`  
Required: no  
Default: `200`  

Render DPI used when rasterizing the source PDF before embedding the OCR text layer (only applies when ``embed_pdf_metadata`` is True). Lower values produce dramatically smaller output PDFs; higher values preserve more detail when zoomed past 200%. Defaults to 200 (good for on-screen viewing); raise toward the source scan DPI for crisper output. Min 50, max 250.

#### `persist_results`

Type: `boolean`  
Required: no  
Default: `false`  

If True, persist the results indefinitely. Defaults to False.

#### `tenant_throttling`

Type: `TenantThrottling`  
Required: no  

Per-tenant throttling for multi-tenant applications. Tag each request with your tenant's id to bound how much of your account's concurrency a single tenant can consume. Account-level throttles still apply.

##### TenantThrottling

Type: `TenantThrottling`  

###### `tenant_id`

Type: `string`  
Required: yes  

Your identifier for the tenant (customer, workspace, organization) this request belongs to. Used only for noisy-neighbor throttling inside your account.

###### `max_share`

Type: `number`  
Required: no  
Default: `0.5`  

Maximum fraction of your account's concurrency ceiling this tenant may use, between 0 (exclusive) and 1. Defaults to 0.5.

##### unknown

Type: `unknown`  

#### `timeout`

Type: `number`  
Required: no  

The timeout for the job in seconds.

##### number

Type: `number`  

##### unknown

Type: `unknown`  

#### `page_range`

Type: `one of 5`  
Required: no  

The page range to process (1-indexed). By default, the entire document is processed. For spreadsheets, you can also provide a list of sheet names.

##### PageRange

Type: `PageRange`  

###### `start`

Type: `number`  
Required: no  

The page number to start processing from (1-indexed).

###### number

Type: `number`  

###### unknown

Type: `unknown`  

###### `end`

Type: `number`  
Required: no  

The page number to stop processing at (1-indexed).

###### number

Type: `number`  

###### unknown

Type: `unknown`  

##### PageRange[]

Type: `PageRange[]`  

###### PageRange

Type: `PageRange`  

###### `start`

Type: `number`  
Required: no  

The page number to start processing from (1-indexed).

###### number

Type: `number`  

###### unknown

Type: `unknown`  

###### `end`

Type: `number`  
Required: no  

The page number to stop processing at (1-indexed).

###### number

Type: `number`  

###### unknown

Type: `unknown`  

##### number[]

Type: `number[]`  

###### number

Type: `number`  

##### string[]

Type: `string[]`  

###### string

Type: `string`  

##### unknown

Type: `unknown`  

#### `document_password`

Type: `string`  
Required: no  

Password to decrypt password-protected documents.

##### string

Type: `string`  

##### unknown

Type: `unknown`  

#### `hybrid_vpc`

Type: `HybridVpcSettings`  
Required: no  

Hybrid VPC request-scoped settings.

##### `environment`

Type: `string`  
Required: no  

Named Hybrid VPC environment to use for this request. Only applies when your organization has Hybrid VPC environments configured.

###### string

Type: `string`  

###### unknown

Type: `unknown`  

#### `return_citations`

Type: `boolean`  
Required: no  
Default: `false`  

If True, locate every word of each text block on the page and return the per-word boxes in the block's `extra['word_citations']`. Each entry carries the word's `text`, its `char_start`/`char_end` span in that block's `content` (half-open, tags included), and a `bbox` covering that word on the page, in the same shape as the block's own `bbox` (including `page`). `bbox` is null when the word cannot be located on the page. Table blocks also get `extra['cell_citations']`: one entry per non-empty cell with its `text`, `row_idx` and `col_idx` (0-based lists of every row and column the cell spans, so a cell merged across rows 1 and 2 has `row_idx` `[1, 2]`), and a `bbox` framing the cell's words, null when none of them can be located. Requires r-1 or r-1 mini. Not supported with formatting.merge_tables. Defaults to False.

### `queue_priority`

Type: `string`  
Required: no  
Allowed values: `auto`, `standard`, `batch`  
Default: `auto`  

Queue priority. 'batch' places the job in a lower-priority queue for non-urgent bulk work. 'auto' (alias: 'standard') uses the default queue.

## Execute with cURL

```bash
curl -X POST "https://platform.reducto.ai/parse_async" \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"<value>"}'
```

## Responses

### Response `200`

Category: success  

Successful Response

#### `application/json`

##### Generated example

```json
{
  "job_id": "job_id"
}
```

##### Schema

###### AsyncParseResponse

Type: `AsyncParseResponse`  

###### `job_id`

Type: `string`  
Required: yes  

### Response `422`

Category: client-error  

Validation Error

#### `application/json`

##### Generated example

```json
{
  "detail": [
    {
      "loc": [
        "loc"
      ],
      "msg": "msg",
      "type": "type",
      "ctx": {}
    }
  ]
}
```

##### Schema

###### HTTPValidationError

Type: `HTTPValidationError`  

###### `detail`

Type: `ValidationError[]`  
Required: no  

###### ValidationError

Type: `ValidationError`  

###### `loc`

Type: `string | number[]`  
Required: yes  

###### string | number

Type: `string | number`  

###### string

Type: `string`  

###### number

Type: `number`  

###### `msg`

Type: `string`  
Required: yes  

###### `type`

Type: `string`  
Required: yes  

###### `input`

Type: `unknown`  
Required: no  

###### `ctx`

Type: `object`  
Required: no  

## Related representations

- [Human documentation](/api-reference/api/sections/parse/operations/parse-async/)
- [cURL Markdown](https://docs.reducto.ai/api-reference/api/curl/sections/parse/operations/parse-async.md)
