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.
Book a demoLog in
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
Book a demoLog in
Workflow Endpoints

Batch Run Workflow

POST
https://api.extend.ai/workflow_runs/batch
POST
/workflow_runs/batch
1from extend_ai import Extend
2from extend_ai.workflow_runs import WorkflowRunsCreateBatchRequestInputsItem
3
4client = Extend(
5    token="YOUR_TOKEN_HERE",
6    extend_api_version="2025-04-21",
7)
8
9client.workflow_runs.create_batch(
10    inputs=[
11        WorkflowRunsCreateBatchRequestInputsItem()
12    ],
13)
1{
2  "success": true,
3  "batchId": "batch_zyx987"
4}
This endpoint allows you to efficiently initiate large batches of workflow runs in a single request (up to 1,000 in a single request, but you can queue up multiple batches in rapid succession). It accepts an array of inputs, each containing a file and metadata pair. The primary use case for this endpoint is for doing large bulk runs of >1000 files at a time that can process over the course of a few hours without needing to manage rate limits that would likely occur using the primary run endpoint. Unlike the single [Run Workflow](https://docs.extend.ai/2025-04-21/developers/api-reference/workflow-endpoints/run-workflow) endpoint which returns the details of the created workflow runs immediately, this batch endpoint returns a `batchId`. Our recommended usage pattern is to integrate with [Webhooks](https://docs.extend.ai/2025-04-21/product/webhooks/configuration) for consuming results, using the `metadata` and `batchId` to match up results to the original inputs in your downstream systems. However, you can integrate in a polling mechanism by using a combination of the [List Workflow Runs](https://docs.extend.ai/2025-04-21/developers/api-reference/workflow-endpoints/list-workflow-runs) endpoint to fetch all runs via a batch, and then [Get Workflow Run](https://docs.extend.ai/2025-04-21/developers/api-reference/workflow-endpoints/get-workflow-run) to fetch the full outputs each run. **Priority:** All workflow runs created through this batch endpoint are automatically assigned a priority of 90. **Processing and Monitoring:** Upon successful submission, the endpoint returns a `batchId`. The individual workflow runs are then queued for processing. - **Monitoring:** Track the progress and consume results of individual runs using [Webhooks](https://docs.extend.ai/2025-04-21/product/webhooks/configuration). Subscribe to events like `workflow_run.completed`, `workflow_run.failed`, etc. The webhook payload for these events will include the corresponding `batchId` and the `metadata` you provided for each input. - **Fetching Results:** You can also use the [List Workflow Runs](https://docs.extend.ai/2025-04-21/developers/api-reference/workflow-endpoints/list-workflow-runs) endpoint and filter using the `batchId` query param.
Was this page helpful?
Previous

Correct Workflow Run Outputs

Next
Built with

This endpoint allows you to efficiently initiate large batches of workflow runs in a single request (up to 1,000 in a single request, but you can queue up multiple batches in rapid succession). It accepts an array of inputs, each containing a file and metadata pair. The primary use case for this endpoint is for doing large bulk runs of >1000 files at a time that can process over the course of a few hours without needing to manage rate limits that would likely occur using the primary run endpoint.

Unlike the single Run Workflow endpoint which returns the details of the created workflow runs immediately, this batch endpoint returns a batchId.

Our recommended usage pattern is to integrate with Webhooks for consuming results, using the metadata and batchId to match up results to the original inputs in your downstream systems. However, you can integrate in a polling mechanism by using a combination of the List Workflow Runs endpoint to fetch all runs via a batch, and then Get Workflow Run to fetch the full outputs each run.

Priority: All workflow runs created through this batch endpoint are automatically assigned a priority of 90.

Processing and Monitoring: Upon successful submission, the endpoint returns a batchId. The individual workflow runs are then queued for processing.

  • Monitoring: Track the progress and consume results of individual runs using Webhooks. Subscribe to events like workflow_run.completed, workflow_run.failed, etc. The webhook payload for these events will include the corresponding batchId and the metadata you provided for each input.
  • Fetching Results: You can also use the List Workflow Runs endpoint and filter using the batchId query param.

Authentication

AuthorizationBearer

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

Headers

x-extend-api-version"2025-04-21"OptionalDefaults to 2025-04-21

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.

Request

This endpoint expects an object.
workflowIdstringRequired

The ID of the workflow to run. This ID will start with “workflow_”. This ID can be found viewing the workflow on the Extend platform.

Example: "workflow_BMdfq_yWM3sT-ZzvCnA3f"

inputslist of objectsRequired
An array of input objects to be processed by the workflow. Each object represents a single workflow run to be created. The array must contain at least 1 input and at most 1000 inputs.
versionstringOptional
An optional version of the workflow to use. This can be a specific version number (e.g., `"1"`, `"2"`) found on the Extend platform, or `"draft"` to use the current unpublished draft version. When a version is not supplied, the latest deployed version of the workflow will be used. If no deployed version exists, the draft version will be used.

Response

Successfully queued batch workflow run
successboolean

Indicates whether the batch request was successfully accepted and queued. true signifies success.

batchIdstring

A unique identifier for the submitted batch. This ID can be used to correlate the workflow runs created by this request. You can find this batchId associated with individual runs when listing workflow runs or in webhook payloads.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error

An optional version of the workflow to use. This can be a specific version number (e.g., "1", "2") found on the Extend platform, or "draft" to use the current unpublished draft version. When a version is not supplied, the latest deployed version of the workflow will be used. If no deployed version exists, the draft version will be used.