> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extend.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Processor

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

In general, the recommended way to integrate with Extend in production is via workflows, using the [Run Workflow](/api-reference/endpoint/run_workflow) endpoint.
This is due to several factors:

* file parsing/pre-processing will automatically be reused across multiple processors, which will give you simplicity and cost savings given that many use cases will require multiple processors to be run on the same document.
* workflows provide dedicated human in the loop document review, when needed.
* workflows allow you to model and manage your pipeline with a single endpoint and corresponding UI for modeling and monitoring.

However, there are a number of legitimate use cases and systems where it might be easier to model the pipeline via code and run processors directly. This endpoint is provided for this purpose.

Similar to workflow runs, processor runs are asynchronous and will return a status of `PROCESSING` until the run is complete.
You can [configure webhooks](/api-reference/webhooks) to receive notifications when a processor run is complete or failed.

### Body

<ParamField body="processorId" type="string" required>
  The ID of the processor that will process the input. This ID can be fetched
  from viewing the processor on the Extend platform.
</ParamField>

<ParamField body="file" type="object">
  A file object containing either a URL or base64 encoded content. Must contain
  either fileUrl or fileBase64. Presigned URLs are recommended for most
  production use cases. Supported file types can be found
  [here](/api-reference/supported_file_types).

  <Expandable title="properties" defaultOpen>
    <ParamField body="fileName" type="string" required>
      The name of the file.
    </ParamField>

    <ParamField body="fileUrl" type="string">
      A presigned URL for the file. Though we will download immediately, we
      recommend a 5 - 15 minute expiration time.
    </ParamField>

    <ParamField body="fileBase64" type="string" deprecated>
      Base64 encoded content of the file. Can be used instead of fileUrl in development environments.

      **DEPRECATED**: This field is deprecated and will be removed in a future release. Use the [`/upload` endpoint](/api-reference/endpoint/upload_file) instead.
    </ParamField>

    <ParamField body="fileId" type="string" optional>
      If you already have an Extend file id (for instance from running a parser or a previous file creation) then you can
      run a processor via file id, and any parsed data will be reused.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="rawText" type="string" optional>
  A raw string to be processed. Can be used in place of file when passing raw
  text data streams. Either file or rawText must be provided.
</ParamField>

<ParamField body="version" type="string" default="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 (the default). If 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.
</ParamField>

<ParamField body="priority" type="number" default="50">
  An optional value used to determine the relative order of processor runs when
  rate limiting is in effect. Priority values must be an integer between 1 and
  100 inclusive. Lower values will be prioritized before higher values. The
  default priority value is 50.
</ParamField>

<ParamField body="metadata" type="object">
  An optional object that can be passed in to identify the processor run in your
  systems. It will be returned in the response and webhooks.
</ParamField>

<ParamField body="config" type="object" optional>
  An option to override the config of the processor.

  <Tabs>
    <Tab title="Extraction">
      <Expandable title="properties">
        <ParamField body="type" type="string" required>
          Must be `"EXTRACT"` for extraction processors.
        </ParamField>

        <ParamField body="baseProcessor" type="string" optional>
          The base processor to use. For extractors, this is either `"extraction_performance"` or `"extraction_light"`. See the [base processor documentation](/changelog/overview) for more details.
        </ParamField>

        <ParamField body="baseVersion" type="string" optional>
          The version of the base processor to use (e.g. `"4.0.0"`). If this is provided, `baseProcessor` must be provided as well. See the [processor changelog](/changelog/overview) for available versions.
        </ParamField>

        <ParamField body="schema" type="object">
          The schema that defines the structure of data to extract from documents. One of `schema` or `fields` must be provided. We recommend using `schema` as `fields` is deprecated. See the [extraction processor schema documentation](/api-reference/guides/processor_configs20250421#extraction-processor-schema-json-schema) for more details.
        </ParamField>

        <ParamField body="fields" type="array" deprecated defaultOpen>
          The schema that defines the structure of data to extract from documents. One of `schema` or `fields` must be provided. We recommend using `schema` as `fields` is deprecated. See the [extraction processor schema documentation](/api-reference/guides/processor_configs20250421#extraction-processor-configuration) for more details on using the `fields` shape.

          <Expandable title="properties">
            <ParamField body="id" type="string" required>
              Unique identifier for the field.
            </ParamField>

            <ParamField body="name" type="string" required>
              Human-readable name for the field.
            </ParamField>

            <ParamField body="type" type="string" required>
              Type of the field. Supported values:

              * `string`: Text values
              * `number`: Numeric values
              * `currency`: Monetary values
              * `boolean`: True/false values
              * `date`: Date values
              * `array`: Lists of values (requires schema)
              * `enum`: Values from a predefined list (requires enum)
              * `object`: Nested structure (requires schema)
              * `signature`: Signature information
            </ParamField>

            <ParamField body="description" type="string" required>
              Detailed description of the field, including expected content and format.
            </ParamField>

            <ParamField body="schema" type="array" optional>
              Required when type is "array" or "object". Contains nested field definitions.
            </ParamField>

            <ParamField body="enum" type="array" optional>
              Required when type is "enum". List of allowed values.

              <Expandable title="properties">
                <ParamField body="value" type="string" required>
                  The enum value.
                </ParamField>

                <ParamField body="description" type="string" required>
                  Description of the enum value.
                </ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="extractionRules" type="string" optional>
          Custom rules to guide the extraction process in natural language.
        </ParamField>

        <ParamField body="advancedOptions" type="object" optional>
          Advanced configuration options.

          <Expandable title="properties">
            <ParamField body="fixedPageLimit" type="number" optional>
              Limit processing to a specific number of pages from the beginning of the document.
            </ParamField>

            <ParamField body="documentKind" type="string" optional>
              Provide a hint about the document type (e.g. "invoice", "receipt", etc.).
            </ParamField>

            <ParamField body="keyDefinitions" type="string" optional>
              Define specific key terms or concepts relevant to the document type.
            </ParamField>

            <ParamField body="modelReasoningInsightsEnabled" type="boolean" optional>
              Enable model reasoning insights in the extraction results.
            </ParamField>

            <ParamField body="advancedMultimodalEnabled" type="boolean" optional>
              Enable advanced multimodal processing for better handling of visual elements.
            </ParamField>

            <ParamField body="citationsEnabled" type="boolean" optional>
              Enable citation information for extracted fields.
            </ParamField>

            <ParamField body="advancedFigureParsingEnabled" type="boolean" optional>
              Enable advanced parsing of figures and diagrams in the document.
            </ParamField>

            <ParamField body="chunkingOptions" type="object" optional>
              Options for controlling document chunking.

              <Expandable title="properties">
                <ParamField body="chunkingStrategy" type="string" optional>
                  Strategy for chunking the document. Supported values:

                  * `standard`: Default chunking strategy
                  * `semantic`: Content-aware chunking based on document structure
                </ParamField>

                <ParamField body="customSemanticChunkingRules" type="string" optional>
                  Custom rules for semantic chunking in natural language.
                </ParamField>

                <ParamField body="pageChunkSize" type="number" optional>
                  Number of pages per chunk.
                </ParamField>

                <ParamField body="chunkSelectionStrategy" type="string" optional>
                  Strategy for selecting chunks. Supported values:

                  * `intelligent`: AI-based selection
                  * `confidence`: Select based on confidence score
                  * `take_first`: Always use first chunk
                  * `take_last`: Always use last chunk
                </ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </Tab>

    <Tab title="Classification">
      <Expandable title="properties">
        <ParamField body="type" type="string" required>
          Must be `"CLASSIFY"` for classification processors.
        </ParamField>

        <ParamField body="baseProcessor" type="string" optional>
          The base processor to use. For classifiers, must be `"classification_performance"` or `"classification_light"`. See the [base processor documentation](/changelog/overview) for more details.
        </ParamField>

        <ParamField body="baseVersion" type="string" optional>
          The version of the base processor to use (e.g. `"3.2.0"`). If this is provided, `baseProcessor` must be provided as well. See the [processor changelog](/changelog/overview) for available versions.
        </ParamField>

        <ParamField body="classifications" type="array" required>
          Array of possible classifications for the document.

          <Expandable title="properties">
            <ParamField body="id" type="string" required>
              Unique identifier for the classification. We recommend lowercase, underscore-separated format.
            </ParamField>

            <ParamField body="type" type="string" required>
              Type identifier for the classification.
            </ParamField>

            <ParamField body="description" type="string" required>
              Detailed description of the classification.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="classificationRules" type="string" optional>
          Custom rules to guide the classification process in natural language.
        </ParamField>

        <ParamField body="advancedOptions" type="object" optional>
          Advanced configuration options.

          <Expandable title="properties">
            <ParamField body="fixedPageLimit" type="number" optional>
              Limit processing to a specific number of pages from the beginning of the document.
            </ParamField>

            <ParamField body="context" type="string" optional>
              The context to use for classification. Supported values:
              `default` `max`
            </ParamField>

            <ParamField body="advancedMultimodalEnabled" type="boolean" optional>
              Enable advanced multimodal processing for better handling of visual elements during classification.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </Tab>

    <Tab title="Splitter">
      <Expandable title="properties">
        <ParamField body="type" type="string" required>
          Must be `"SPLITTER"` for splitter processors.
        </ParamField>

        <ParamField body="baseProcessor" type="string" optional>
          The base processor to use. For splitters, this can currently only be `"splitter_performance"`. See the [base processor documentation](/changelog/overview) for more details.
        </ParamField>

        <ParamField body="baseVersion" type="string" optional>
          The version of the base processor to use (e.g. `"1.0.0"`). If this is provided, `baseProcessor` must be provided as well. See the [processor changelog](/changelog/overview) for available versions.
        </ParamField>

        <ParamField body="splitClassifications" type="array" required>
          Array of classifications that define the possible types of document sections.

          <Expandable title="properties">
            <ParamField body="id" type="string" required>
              Unique identifier for the split classification.
            </ParamField>

            <ParamField body="type" type="string" required>
              Type identifier for the split classification.
            </ParamField>

            <ParamField body="description" type="string" required>
              Detailed description of the document section type.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="splitRules" type="string" optional>
          Custom rules to guide the document splitting process in natural language.
        </ParamField>

        <ParamField body="advancedOptions" type="object" optional>
          Advanced configuration options.

          <Expandable title="properties">
            <ParamField body="fixedPageLimit" type="number" optional>
              Limit processing to a specific number of pages from the beginning of the document.
            </ParamField>

            <ParamField body="splitMethod" type="string" optional>
              Method to use for splitting. Supported values:

              * `high_precision`: More accurate but potentially slower
              * `low_latency`: Faster but potentially less precise
            </ParamField>

            <ParamField body="splitIdentifierRules" type="string" optional />

            <ParamField body="splitExcelDocumentsBySheetEnabled" type="boolean" optional>
              For Excel documents, split by worksheet.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </Tab>
  </Tabs>
</ParamField>

<RequestExample>
  ```bash Example Request theme={null}
  curl --location --request POST 'https://api-prod.extend.app/v1/processor_runs' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --data '{
      "processorId": "dp_1234",
      "file": {
          "fileName": "example.pdf",
          "fileUrl": "https://test.s3.amazonaws.com/example.pdf"
      },
      "version": "1.0",
      "priority": 50,
      "metadata": {
          "internal_id": "id_1234"
      }
  }'
  ```

  ```javascript Node.js theme={null}
  const axios = require("axios");

  const runProcessor = async () => {
    try {
      const response = await axios.post(
        "https://api-prod.extend.app/v1/processor_runs",
        {
          processorId: "dp_1234",
          file: {
            fileName: "example.pdf",
            fileUrl: "https://test.s3.amazonaws.com/example.pdf",
          },
          version: "1.0",
          priority: 50,
          metadata: {
            internal_id: "id_1234",
          },
        },
        {
          headers: {
            Authorization: "Bearer <API_TOKEN>",
            "Content-Type": "application/json",
          },
        }
      );

      console.log("Processor run created:", response.data);
    } catch (error) {
      console.error("Error:", error.response?.data || error.message);
    }
  };

  runProcessor();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api-prod.extend.app/v1/processor_runs"
  headers = {
      "Authorization": "Bearer <API_TOKEN>",
      "Content-Type": "application/json"
  }
  payload = {
      "processorId": "dp_1234",
      "file": {
          "fileName": "example.pdf",
          "fileUrl": "https://test.s3.amazonaws.com/example.pdf"
      },
      "version": "1.0",
      "priority": 50,
      "metadata": {
          "internal_id": "id_1234"
      }
  }

  try:
      response = requests.post(url, json=payload, headers=headers)
      response.raise_for_status()
      print("Processor run created:", response.json())
  except requests.exceptions.RequestException as e:
      print("Error:", e)
  ```
</RequestExample>

### Response

<ResponseField name="success" type="boolean">
  A true or false value indicating whether the processor run was created
  successfully.
</ResponseField>

<ResponseField name="processorRun" type="object">
  Details about the created processor run.

  See the [ProcessorRun object](/api-reference/objects/processor_run) for more details.
</ResponseField>

### Common errors

<ResponseField name="400 Bad Request">
  Returned when: - Required fields are missing (e.g., `processorId`) - Neither
  `file` nor `rawText` is provided - Invalid files: - The provided `fileUrl` is
  invalid - The provided `fileBase64` is invalid - It's an unsupported file type

  * The file is corrupted or otherwise cannot be downloaded - The `priority`
    value is outside the allowed range (must be between 1 and 100)
</ResponseField>

<ResponseField name="404 Not Found">
  Returned when: - The specified processor ID doesn't exist - The specified
  processor version doesn't exist
</ResponseField>

<ResponseField name="401 Unauthorized">
  Returned when: - The API token is missing - The API token is invalid
</ResponseField>

<ResponseField name="403 Forbidden">
  Returned when: - The authenticated workspace doesn't have permission to access
  the specified processor - The API token doesn't have sufficient permissions
</ResponseField>

<ResponseExample>
  ```json Example Response theme={null}
  {
    "success": true,
    "processorRun": {
      "object": "document_processor_run",
      "id": "dpr_1234",
      "output": null, // Will be null until the run is processed
      "processorId": "dp_5678",
      "processorVersionId": "dpv_91011",
      "processorName": "Invoice Extractor",
      "status": "PROCESSING",
      "metadata": {
        "internal_id": "id_1234"
      },
      "reviewed": false,
      "edited": false,
      "edits": null,
      "type": "EXTRACT",
      "config": {
        "fields": [
          {
            "id": "total_amount",
            "name": "Total Amount",
            "type": "currency"
          }
        ]
      },
      "files": [
        {
          "name": "example.pdf"
        }
      ],
      "url": "https://dashboard.extend.app/runs/dpr_1234"
    }
  }
  ```
</ResponseExample>