Run Workflow

POST

/workflow_runs

POST

/workflow_runs

from extend_ai import Extend
client = Extend(
    token="YOUR_TOKEN_HERE",
    extend_api_version="2026-02-09",
)
client.workflow_runs.create(
    workflow={
        "id": "wf_1234567890"
    },
    package={
        "files": [
            {
                "url": "https://example.com/invoice.pdf"
            },
            {
                "url": "https://example.com/bill-of-lading.pdf"
            },
            {
                "id": "file_xK9mLPqRtN3vS8wF5hB2cQ"
            }
        ]
    },
)

{
  "object": "workflow_run",
  "id": "workflow_run_xKm9pNv3qWsY_jL2tR5Dh",
  "workflow": {
    "object": "workflow",
    "id": "workflow_BMlfq_yWM3sT-ZzvCnA3f",
    "name": "Invoice Processing",
    "createdAt": "2024-03-21T16:45:00Z",
    "updatedAt": "2024-03-21T16:45:00Z",
    "createdBy": {
      "type": "user",
      "email": "matt@extend.app"
    }
  },
  "workflowVersion": {
    "object": "workflow_version",
    "id": "workflow_version_Zk9mNP12Qw4-yTv8BdR3H",
    "version": "1",
    "name": "Production v1",
    "createdAt": "2024-03-21T16:45:00Z",
    "createdBy": {
      "type": "user",
      "email": "matt@extend.app"
    }
  },
  "dashboardUrl": "https://dashboard.extend.ai/workflows/workflow_run_xKm9pNv3qWsY_jL2tR5Dh",
  "status": "PENDING",
  "metadata": {},
  "batchId": "batch_7Ws31-F5",
  "files": [
    {
      "object": "file",
      "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
      "name": "Invoices.pdf",
      "type": "PDF",
      "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
      "metadata": {
        "pageCount": 30,
        "parentSplit": {
          "id": "string",
          "type": "Invoice",
          "identifier": "other_2_9",
          "startPage": 1,
          "endPage": 10
        }
      },
      "createdAt": "2024-03-21T16:45:00Z",
      "updatedAt": "2024-03-21T16:45:00Z"
    }
  ],
  "failureReason": "string",
  "failureMessage": "string",
  "initialRunAt": "2025-04-28T17:01:39.285Z",
  "reviewedByUser": "jane.doe@example.com",
  "reviewed": true,
  "rejectionNote": "string",
  "reviewedAt": "2024-03-21T16:45:00Z",
  "startTime": "2024-03-21T15:30:00Z",
  "endTime": "2024-03-21T15:35:00Z",
  "stepRuns": [
    {
      "object": "workflow_step_run",
      "id": "workflow_step_run_xK9mLPqRtN3vS8wF5hB2cQ",
      "workflowRunId": "workflow_run_xKm9pNv3qWsY_jL2tR5Dh",
      "stepType": "PARSE",
      "status": "PROCESSED",
      "files": [
        {
          "object": "file",
          "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
          "name": "Invoices.pdf",
          "type": "PDF",
          "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
          "metadata": {
            "pageCount": 30,
            "parentSplit": {
              "id": "string",
              "type": "Invoice",
              "identifier": "other_2_9",
              "startPage": 1,
              "endPage": 10
            }
          },
          "createdAt": "2024-03-21T16:45:00Z",
          "updatedAt": "2024-03-21T16:45:00Z"
        }
      ],
      "step": {
        "object": "workflow_step",
        "id": "step_xK9mLPqRtN3vS8wF5hB2cQ",
        "name": "Validate Invoice Total",
        "type": "PARSE"
      },
      "result": {
        "parseRun": {
          "object": "parse_run",
          "id": "pr_xK9mLPqRtN3vS8wF5hB2cQ",
          "batchId": "bpar_Xj8mK2pL9nR4vT7qY5wZ",
          "file": {
            "object": "file",
            "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
            "name": "Invoices.pdf",
            "type": "PDF",
            "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
            "metadata": {
              "pageCount": 30,
              "parentSplit": {
                "id": "string",
                "type": "Invoice",
                "identifier": "other_2_9",
                "startPage": 1,
                "endPage": 10
              }
            },
            "createdAt": "2024-03-21T16:45:00Z",
            "updatedAt": "2024-03-21T16:45:00Z"
          },
          "status": "PENDING",
          "failureReason": "FILE_TYPE_NOT_SUPPORTED",
          "failureMessage": "File type not supported for parsing.",
          "metadata": {},
          "output": {
            "chunks": [
              {
                "object": "chunk",
                "type": "page",
                "content": "This is the content of the chunk.",
                "metadata": {
                  "pageRange": {
                    "start": 1,
                    "end": 1
                  },
                  "minOcrConfidence": 1.1,
                  "avgOcrConfidence": 1.1
                },
                "blocks": [
                  {
                    "object": "block",
                    "id": "string",
                    "parentBlockId": "string",
                    "type": "text",
                    "content": "string",
                    "details": {},
                    "metadata": {
                      "page": {
                        "number": 1,
                        "width": 1.1,
                        "height": 1.1
                      },
                      "sheet": {
                        "index": 0,
                        "name": "Sheet1"
                      },
                      "minOcrConfidence": 1.1,
                      "avgOcrConfidence": 1.1
                    },
                    "polygon": [
                      {
                        "x": 10,
                        "y": 20
                      }
                    ],
                    "boundingBox": {
                      "left": 10,
                      "top": 10,
                      "right": 20,
                      "bottom": 20
                    },
                    "children": [
                      null
                    ]
                  }
                ]
              }
            ],
            "ocr": {
              "words": [
                {
                  "content": "string",
                  "boundingBox": {
                    "left": 10,
                    "top": 10,
                    "right": 20,
                    "bottom": 20
                  },
                  "confidence": 1.1,
                  "pageNumber": 1.1,
                  "blockId": "string",
                  "rotation": 1.1
                }
              ]
            },
            "metadata": {
              "originalMimeType": "string",
              "finalMimeType": "string",
              "pages": [
                {
                  "number": 1,
                  "rotationApplied": 1,
                  "originalPageWidth": 1.1,
                  "originalPageHeight": 1.1,
                  "dpi": 1.1
                }
              ]
            }
          },
          "outputUrl": "https://...",
          "metrics": {
            "processingTimeMs": 1234,
            "pageCount": 5
          },
          "config": {
            "target": "markdown",
            "chunkingStrategy": {
              "type": "page",
              "options": {
                "minCharacters": 500,
                "maxCharacters": 10000
              }
            },
            "engine": "parse_performance",
            "engineVersion": "latest",
            "blockOptions": {
              "figures": {
                "enabled": true,
                "figureImageClippingEnabled": true,
                "advancedChartExtractionEnabled": false,
                "customInstructions": "string"
              },
              "tables": {
                "enabled": true,
                "targetFormat": "html",
                "tableHeaderContinuationEnabled": false,
                "cellBlocksEnabled": false,
                "agentic": {
                  "enabled": false,
                  "customInstructions": "string"
                }
              },
              "text": {
                "signatureDetectionEnabled": false,
                "agentic": {
                  "enabled": false,
                  "customInstructions": "string"
                }
              },
              "keyValue": {
                "blankFieldFormattingEnabled": false
              },
              "barcodes": {
                "imageClippingEnabled": false,
                "readingEnabled": false
              },
              "formulas": {
                "enabled": false
              }
            },
            "advancedOptions": {
              "pageRotationEnabled": true,
              "pageRanges": [
                {
                  "start": 1,
                  "end": 10
                },
                {
                  "start": 20,
                  "end": 30
                }
              ],
              "excelParsingMode": "basic",
              "excelSkipHiddenContent": false,
              "excelUseRawCellValues": false,
              "excelSkipCalculation": true,
              "excelIncludeCellMetadata": false,
              "excelIncludeCellFormatting": false,
              "verticalGroupingThreshold": 1,
              "returnOcr": {
                "words": false
              },
              "alwaysConvertToPdf": false,
              "enrichmentFormat": "xml",
              "imageConversionQuality": "medium",
              "formattingDetection": [
                {
                  "type": "change_tracking"
                }
              ]
            }
          },
          "usage": {
            "credits": 9,
            "totalCredits": 15,
            "breakdown": [
              {
                "object": "parse_run",
                "id": "pr_3UZSj69pYZDKHFuuX57ic",
                "credits": 6,
                "charges": [
                  {
                    "product": "extraction_performance",
                    "unit": "page",
                    "quantity": 10,
                    "credits": 30
                  },
                  {
                    "product": "review_agent",
                    "unit": "page",
                    "quantity": 10,
                    "credits": 10
                  },
                  {
                    "product": "agentic_text_correction",
                    "unit": "page",
                    "quantity": 3,
                    "credits": 3,
                    "pages": [
                      2,
                      4,
                      7
                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    }
  ],
  "usage": {
    "credits": 9,
    "totalCredits": 15,
    "breakdown": [
      {
        "object": "parse_run",
        "id": "pr_3UZSj69pYZDKHFuuX57ic",
        "credits": 6,
        "charges": [
          {
            "product": "extraction_performance",
            "unit": "page",
            "quantity": 10,
            "credits": 30
          },
          {
            "product": "review_agent",
            "unit": "page",
            "quantity": 10,
            "credits": 10
          },
          {
            "product": "agentic_text_correction",
            "unit": "page",
            "quantity": 3,
            "credits": 3,
            "pages": [
              2,
              4,
              7
            ]
          }
        ]
      }
    ]
  }
}

Run a workflow. A workflow is a sequence of steps that process files and data in a specific order to achieve a desired outcome. See Async Processing for a full guide on polling helpers and webhooks.

Pass file for a single document use case (more common), or package to process 2–50 files together as one package in a single run where context across files is used together to determine final output. Exactly one of file or package must be provided. See Package runs for details.

Polling with the SDK

The SDK provides a createAndPoll / create_and_poll method that handles polling automatically, returning when the run reaches a terminal state (PROCESSED, FAILED, CANCELLED, NEEDS_REVIEW, or REJECTED):

TypeScript

Python

Java

const result = await client.workflowRuns.createAndPoll({
  workflow: { id: "wf_abc123" },
  file: { url: "https://..." }
});
// Returns when the workflow run reaches a terminal state
console.log(result.status);
console.log(result.stepRuns);

Workflow runs can take a long time. Complex workflows may run for hours. For long-running workflows, consider using webhooks instead of polling.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.

workflowobjectRequired

The workflow to run.

fileobjectOptional

The file to be processed. Supported file types can be found here. Files can be provided as a URL, an Extend file ID, or raw text. Mutually exclusive with package — provide one or the other. If you wish to process many files as independent runs, consider using the Batch Run Workflow endpoint.

packageobjectOptional

A set of 2–50 files to process together in a single workflow run. Mutually exclusive with file — provide one or the other.

outputslist of objectsOptional

Predetermined outputs to be used for the workflow run. Generally not recommended for most use cases, however, can be useful in cases of overriding a classification in a workflow, or a subset of extraction fields when data is known. Not supported on package runs — a package run produces a single merged result across all files and cannot accept pre-supplied per-processor outputs.

priorityintegerOptional1-100Defaults to 50

An optional value used to determine the relative order of runs 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. It will be returned back to you in the response and webhooks. Maximum size is 10KB.

To categorize 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.

secretsobjectOptional

An optional object containing secrets to be used by processors within the workflow for this specific run.

Response

Successfully created workflow run

objectenum

The type of object. In this case, it will always be "workflow_run".

Allowed values:

idstring

The ID of the workflow run.

Example: "workflow_run_xKm9pNv3qWsY_jL2tR5Dh"

workflowobject

A summary representation of a workflow.

workflowVersionobject

A summary representation of a workflow version (without steps).

dashboardUrlstring

A URL to view this workflow run in the Extend dashboard.

Example: "https://dashboard.extend.ai/workflows/workflow_run_xKm9pNv3qWsY_jL2tR5Dh"

statusenum

The status of a workflow run:

"PENDING" - The workflow run is waiting to be processed
"PROCESSING" - The workflow run is currently processing
"NEEDS_REVIEW" - The workflow run requires manual review
"REJECTED" - The workflow run was rejected during review
"PROCESSED" - The workflow run completed successfully
"FAILED" - The workflow run encountered an error
"CANCELLED" - The workflow run was cancelled
"CANCELLING" - The workflow run is being cancelled

metadatamap from strings to any

The metadata that was passed in when running the Workflow.

batchIdstring or null

The batch ID of the WorkflowRun. If this WorkflowRun was created as part of a batch of files, all runs in that batch will have the same batch ID.

Example: "batch_7Ws31-F5"

fileslist of objects

failureReasonstring or null

The reason why the workflow run failed. Will only be included if the workflow run status is "FAILED".

failureMessagestring or null

A more detailed message about the failure. Will only be included if the workflow run status is "FAILED".

initialRunAtstring or nullformat: "date-time"

The time (in UTC) at which the workflow run was created. Will follow the RFC 3339 format. Will be null if the run hasn’t started yet.

Example: "2025-04-28T17:01:39.285Z"

reviewedByUserstring or null

The email address of the person who reviewed the workflow run. Will be null if the workflow run has not been reviewed.

Example: "jane.doe@example.com"

reviewedboolean

Whether the workflow run has been reviewed.

rejectionNotestring or null

A note that is added if a workflow run is rejected.

Example: "Invalid invoice format"

reviewedAtstring or nullformat: "date-time"

The time (in UTC) at which the workflow run was reviewed. Will follow the RFC 3339 format. Will be null if the workflow run has not been reviewed.

Example: "2024-03-21T16:45:00Z"

startTimestring or nullformat: "date-time"

The time (in UTC) at which the workflow run started executing. This will always be after the initialRunAt time. Will follow the RFC 3339 format. Will be null if the workflow run has not started executing.

Example: "2024-03-21T15:30:00Z"

endTimestring or nullformat: "date-time"

The time (in UTC) that the workflow finished executing. Will follow the RFC 3339 format. Will be null if the workflow run has not finished executing.

Example: "2024-03-21T15:35:00Z"

stepRunslist of objects

An array of WorkflowStepRun objects. Each WorkflowStepRun represents a single run of a WorkflowStep and contains details about the step's execution and result.

usageobject or null

Usage credits consumed by this workflow run, including a breakdown of every contributing child run.

Availability: Will not be returned for runs created before October 7, 2025 or for customers on legacy billing systems.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error