> ## Documentation Index > Fetch the complete documentation index at: https://docs.extend.ai/llms.txt > Use this file to discover all available pages before exploring further. > > ## API version > The current API version is `2026-02-09`, served at the site root (no version prefix in URLs). > If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version. > Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version. > Do not treat older-version pages as the source of truth for new integrations. # Batch Run Workflow 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](/2024-12-23/developers/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](/2024-12-23/developers/webhooks/events) 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](/2024-12-23/developers/workflow-endpoints/list-workflow-runs) endpoint to fetch all runs via a batch, and then [Get Workflow Run](/2024-12-23/developers/workflow-endpoints/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. #### Properties **`file`** `object` Specifies a file to be processed. Either `file` or `rawText` must be provided for each input. #### File Object Properties **`fileUrl`** `string` A presigned URL for the file. For the batch endpoint, we suggest a slightly longer expiration time, ideally 30 minutes for a worst case scenario. --- **`fileId`** `string` An existing Extend file ID (e.g., from a previous workflow run or file upload). If provided, Extend will reuse the existing file data. Either `fileUrl` or `fileId` must be provided if the `file` object is used. --- **`fileName`** `string` The name to associate with the file. If not provided when using `fileUrl`, the name may be inferred from the URL. This param is only for your reference, and will be rendered in our dashboard, it is not used by the workflow. --- --- **`rawText`** `string` A string containing raw text data to be processed. This will be treated as a `.txt` file by the workflow. Use the `file` parameter for structured data or specific file types. Either `file` or `rawText` must be provided for each input. --- **`metadata`** `object` An optional object containing arbitrary key-value pairs to associate with this specific workflow run. This metadata will be included in webhook payloads and responses when fetching the workflow run details. To categorize runs for billing and usage tracking, include usage tags with the `extend:usage_tags` key. --- **`secrets`** `object` An optional object containing secrets to be used by processors within the workflow for this specific run. Secrets provided here override any globally configured secrets for the workflow. --- --- ### 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](/2024-12-23/developers/webhooks/events). 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](/2024-12-23/developers/workflow-endpoints/list-workflow-runs) endpoint and filter using the `batchId` query param. **`Bash`** ```bash Bash curl --location --request POST 'https://api-prod.extend.app/workflow_runs/batch' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --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" } } ] }' ``` **`Node.js`** ```javascript Node.js async function runWorkflowBatch() { const apiToken = ""; const url = "https://api-prod.extend.app/workflow_runs/batch"; const payload = { workflowId: "workflow_abc789", version: "2", inputs: [ { file: { fileName: "invoice_1.pdf", fileUrl: "https://your-presigned-url.s3.amazonaws.com/invoice_1.pdf?..." }, name: "Run for Invoice 1", metadata: { customer_id: "cust_123", source": "batch_upload" } }, { file: { fileId: "file_def456" }, name: "Run for Existing File DEF456", metadata: { customer_id": "cust_456", source": "batch_upload" } }, { rawText: "This is the raw text content for the third run.", name: "Run for Raw Text Input", metadata: { internal_ref": "ref_789" } } ] }; try { const response = await fetch(url, { method: "POST", headers: { "Authorization": `Bearer ${apiToken}`, "Content-Type": "application/json", }, body: JSON.stringify(payload), }); const data = await response.json(); if (!response.ok) { console.error(`Error: ${response.status}`, data); // Log the response text for more detailed debugging if needed // console.error("Response text:", await response.text()); return; } console.log("Success:", data); } catch (error) { console.error("Request failed:", error); } } runWorkflowBatch(); ``` **`Python`** ```python Python import requests import json api_token = "" url = "https://api-prod.extend.app/workflow_runs/batch" payload = { "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" } } ] } headers = { "Authorization": f"Bearer {api_token}", "Content-Type": "application/json" } response = requests.post(url, headers=headers, data=json.dumps(payload)) print(response.status_code) print(response.json()) ``` ### 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. **`200 OK`** ```json 200 OK { "success": true, "batchId": "batch_zyx987" } ``` **`400 Bad Request`** ```json 400 Bad Request { "success": false, "error": "Validation Error: Array must contain at most 1000 element(s): param: inputs" } ``` **`404 Not Found`** ```json 404 Not Found { "success": false, "error": "Resource not found." } ``` > Ship your document processing with Extend. Get started with our APIs, SDKs, and guides.