For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
GuidesAPI ReferenceChangelogModel Versioning
GuidesAPI ReferenceChangelogModel Versioning
    • Getting Started
    • Authentication
    • API Versioning
    • SDKs
    • Deployments
  • Processor Endpoints
    • POSTRun Processor
    • GETGet Processor Run
    • GETList Processor Runs
    • POSTCancel Processor Run
    • DELDelete Processor Run
    • GETGet Batch Processor Run
    • GETList Processors
    • POSTCreate Processor
    • POSTUpdate Processor
    • POSTPublish Processor Version
    • GETGet Processor Version
    • GETList Processor Versions
  • Parse Endpoints
    • POSTParse File
    • POSTParse File Async
    • GETGet Parser Run
    • DELDelete Parser Run
  • Workflow Endpoints
    • POSTRun Workflow
    • GETGet Workflow Run
    • GETList Workflow Runs
    • POSTUpdate Workflow Run
    • POSTCancel Workflow Run
    • DELDelete Workflow Run
    • POSTCreate Workflow
    • POSTBatch Run Workflow
    • POSTCorrect Workflow Run Outputs
  • File Endpoints
    • POSTUpload File
    • GETGet File
    • DELDelete File
    • GETList Files
    • POSTCreate File
  • Edit Endpoints
    • POSTEdit File
    • POSTEdit File Async
    • POSTGenerate Edit Schema
    • GETGet Edit Run
    • DELDelete Edit Run
    • GETGet Edit Template
  • Evaluation Set Endpoints
    • GETGet Evaluation Set
    • GETList Evaluation Sets
    • POSTCreate Evaluation Set
    • GETList Evaluation Set Items
    • POSTCreate Evaluation Set Item
    • POSTUpdate Evaluation Set Item
    • DELDelete Evaluation Set Item
    • POSTBulk Create Evaluation Set Items
LogoLogo
Processor Endpoints

Run Processor

POST
https://api.extend.ai/processor_runs
POST
/processor_runs
1import { ExtendClient } from "extend-ai";
2
3const client = new ExtendClient({ token: "YOUR_TOKEN" });
4await client.processorRun.create({
5    processorId: "processor_id_here"
6});
1{
2  "success": true,
3  "processorRun": {
4    "object": "document_processor_run",
5    "id": "dpr_l39vTgFDiB13heVuMQnUa",
6    "processorId": "dp_SmJyN3LMx9kW_YmFTxTha",
7    "processorVersionId": "dpv_YrgxmNn83sAO0JChhmLpa",
8    "processorName": "My Processor",
9    "status": "PROCESSING",
10    "output": {},
11    "reviewed": false,
12    "edited": false,
13    "edits": {},
14    "type": "EXTRACT",
15    "config": {
16      "type": "EXTRACT",
17      "schema": {
18        "type": "object",
19        "required": [
20          "name",
21          "age"
22        ],
23        "properties": {
24          "age": {
25            "type": [
26              "number",
27              "null"
28            ],
29            "description": "The age of the person"
30          },
31          "name": {
32            "type": [
33              "string",
34              "null"
35            ],
36            "description": "The name of the person"
37          }
38        },
39        "additionalProperties": false
40      },
41      "advancedOptions": {
42        "advancedMultimodalEnabled": true,
43        "advancedFigureParsingEnabled": false,
44        "chunkingOptions": {
45          "chunkingStrategy": "standard",
46          "chunkSelectionStrategy": "intelligent"
47        }
48      }
49    },
50    "files": [
51      {
52        "object": "file",
53        "id": "file_0QyyVL9rrOd0_WllDDCNa",
54        "name": "My File",
55        "metadata": {},
56        "createdAt": "2025-05-12T21:22:37.318000+00:00",
57        "updatedAt": "2025-05-12T21:22:37.324000+00:00",
58        "type": "PDF",
59        "usage": {
60          "credits": 10
61        }
62      }
63    ],
64    "mergedProcessors": [],
65    "url": "https://dashboard.extend.ai/runs/dpr_l39vTgFDiB13heVuMQnUa",
66    "initialOutput": {},
67    "usage": {
68      "credits": 3.5
69    }
70  }
71}
Run processors (extraction, classification, splitting, etc.) on a given document. **Synchronous vs Asynchronous Processing:** - **Asynchronous (default)**: Returns immediately with `PROCESSING` status. Use webhooks or polling to get results. - **Synchronous**: Set `sync: true` to wait for completion and get final results in the response (5-minute timeout). **For asynchronous processing:** - You can [configure webhooks](https://docs.extend.ai/product/webhooks/configuration) to receive notifications when a processor run is complete or failed. - Or you can [poll the get endpoint](https://docs.extend.ai/2025-04-21/developers/api-reference/processor-endpoints/get-processor-run) for updates on the status of the processor run.
Was this page helpful?
Previous

Get Processor Run

Next
Built with

Run processors (extraction, classification, splitting, etc.) on a given document.

Synchronous vs Asynchronous Processing:

  • Asynchronous (default): Returns immediately with PROCESSING status. Use webhooks or polling to get results.
  • Synchronous: Set sync: true to wait for completion and get final results in the response (5-minute timeout).

For asynchronous processing:

  • You can configure webhooks to receive notifications when a processor run is complete or failed.
  • Or you can poll the get endpoint for updates on the status of the processor run.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

x-extend-api-version"2025-04-21"Optional
API version to use for the request. If you do not specify a version, you will either receive a `400 Bad Request` or be set to a previous legacy version. See [API Versioning](https://docs.extend.ai/2025-04-21/developers/api-versioning) for more details.

Request

This endpoint expects an object.
processorIdstringRequired

The ID of the processor to be run.

Example: "dp_Xj8mK2pL9nR4vT7qY5wZ"

versionstringOptionalDefaults to latest
An optional version of the processor to use. When not supplied, the most recent published version of the processor will be used. Special values include: - `"latest"` for the most recent published version. If there are no published versions, the draft version will be used. - `"draft"` for the draft version. - Specific version numbers corresponding to versions your team has published, e.g. `"1.0"`, `"2.2"`, etc.
fileobjectOptional
The file to be processed. One of `file` or `rawText` must be provided. Supported file types can be found [here](https://docs.extend.ai/2025-04-21/product/general/supported-file-types).
rawTextstringOptional

A raw string to be processed. Can be used in place of file when passing raw text data streams. One of file or rawText must be provided.

syncbooleanOptionalDefaults to false
Whether to run the processor synchronously. When `true`, the request will wait for the processor run to complete and return the final results. When `false` (default), the request returns immediately with a `PROCESSING` status, and you can poll for completion or use webhooks. For production use cases, we recommending leaving sync off and building around an async integration for more resiliency, unless your use case is predictably fast (e.g. sub < 30 seconds) run time or otherwise have integration constraints that require a synchronous API. **Timeout**: Synchronous requests have a 5-minute timeout. If the processor run takes longer, it will continue processing asynchronously and you can retrieve the results via the GET endpoint.
priorityintegerOptional1-100Defaults to 50
An optional value used to determine the relative order of ProcessorRuns when rate limiting is in effect. Lower values will be prioritized before higher values.
metadatamap from strings to anyOptional
An optional object that can be passed in to identify the run of the document processor. It will be returned back to you in the response and webhooks. To categorize processor runs for billing and usage tracking, include `extend:usage_tags` with an array of string values (e.g., `{"extend:usage_tags": ["production", "team-eng", "customer-123"]}`). Tags must contain only alphanumeric characters, hyphens, and underscores; any special characters will be automatically removed.
configobjectOptional
The configuration for the processor run. If this is provided, this config will be used. If not provided, the config for the specific version you provide will be used. The type of configuration must match the processor type.

Response

Successfully created processor run
successboolean
processorRunobject

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
429
Too Many Requests Error

API version to use for the request. If you do not specify a version, you will either receive a 400 Bad Request or be set to a previous legacy version. See API Versioning for more details.

An optional version of the processor to use. When not supplied, the most recent published version of the processor will be used. Special values include:

  • "latest" for the most recent published version. If there are no published versions, the draft version will be used.
  • "draft" for the draft version.
  • Specific version numbers corresponding to versions your team has published, e.g. "1.0", "2.2", etc.

The file to be processed. One of file or rawText must be provided. Supported file types can be found here.

Whether to run the processor synchronously. When true, the request will wait for the processor run to complete and return the final results. When false (default), the request returns immediately with a PROCESSING status, and you can poll for completion or use webhooks. For production use cases, we recommending leaving sync off and building around an async integration for more resiliency, unless your use case is predictably fast (e.g. sub < 30 seconds) run time or otherwise have integration constraints that require a synchronous API.

Timeout: Synchronous requests have a 5-minute timeout. If the processor run takes longer, it will continue processing asynchronously and you can retrieve the results via the GET endpoint.

An optional object that can be passed in to identify the run of the document processor. It will be returned back to you in the response and webhooks.

To categorize processor runs for billing and usage tracking, include extend:usage_tags with an array of string values (e.g., {"extend:usage_tags": ["production", "team-eng", "customer-123"]}). Tags must contain only alphanumeric characters, hyphens, and underscores; any special characters will be automatically removed.