curl --location --request POST 'https://api-prod.extend.app/workflow_runs/batch' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
    "workflowId": "workflow_abc789",
    "version": "2",
    "inputs": [
      {
        "file": {
          "fileName": "invoice_1.pdf",
          "fileUrl": "https://your-presigned-url.s3.amazonaws.com/invoice_1.pdf?..."
        },
        "metadata": {
          "customer_id": "cust_123",
          "source": "batch_upload"
        }
      },
      {
        "file": {
          "fileId": "file_def456"
        },
        "metadata": {
          "customer_id": "cust_456",
          "source": "batch_upload"
        }
      },
      {
        "rawText": "This is the raw text content for the third run.",
        "metadata": {
          "internal_ref": "ref_789"
        }
      }
    ]
}'

{
  "success": true,
  "batchId": "batch_zyx987"
}
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.

​
Body

​
workflowId
string
required
The ID of the workflow that the inputs will be run through. This ID can be found by viewing the workflow on the Extend platform.
​
version
string
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.
​
inputs
Input[]
required
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.

​
Response

​
success
boolean
Indicates whether the batch request was successfully accepted and queued. true signifies success.
​
batchId
string
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.

​
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.
curl --location --request POST 'https://api-prod.extend.app/workflow_runs/batch' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
    "workflowId": "workflow_abc789",
    "version": "2",
    "inputs": [
      {
        "file": {
          "fileName": "invoice_1.pdf",
          "fileUrl": "https://your-presigned-url.s3.amazonaws.com/invoice_1.pdf?..."
        },
        "metadata": {
          "customer_id": "cust_123",
          "source": "batch_upload"
        }
      },
      {
        "file": {
          "fileId": "file_def456"
        },
        "metadata": {
          "customer_id": "cust_456",
          "source": "batch_upload"
        }
      },
      {
        "rawText": "This is the raw text content for the third run.",
        "metadata": {
          "internal_ref": "ref_789"
        }
      }
    ]
}'

{
  "success": true,
  "batchId": "batch_zyx987"
}

​
Error Responses

Common errors include:
  • 400 Bad Request: Invalid request body (e.g., missing required fields, array size limits exceeded, issues with fileUrl or fileId). The response body will contain an error message detailing the specific validation issues. Can also indicate issues accessing a provided fileUrl.
  • 401 Unauthorized: Missing or invalid API token.
  • 403 Forbidden: The API token does not have permission to access the specified workflow.
  • 404 Not Found: The specified workflowId or version does not exist.
  • 429 Too Many Requests: The request was rate limited. Please try again later.
  • 500 Internal Server Error: An unexpected error occurred on the server.
{
  "success": false,
  "error": "Validation Error: Array must contain at most 1000 element(s): param: inputs"
}

{
  "success": false,
  "error": "Resource not found."
}