> This page is for version v2025-04-21. > For other versions, use one of these documentation indexes: > - v2026-02-09 (default): https://docs.extend.ai/2026-02-09/llms.txt > - v2025-04-21: https://docs.extend.ai/2025-04-21/llms.txt > - v2024-12-23: https://docs.extend.ai/2024-12-23/llms.txt > ## 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 POST https://api.extend.ai/workflow_runs/batch Content-Type: application/json 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:** By default, workflow runs created through this batch endpoint are assigned a priority of 90. You can override this by passing an optional `priority` value (1–100) in the request body — lower values run first. **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. Reference: https://docs.extend.ai/2025-04-21/developers/api-reference/workflow-endpoints/batch-run-workflow ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Headers - `x-extend-api-version` ("2025-04-21", optional, default: 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](https://docs.extend.ai/2025-04-21/developers/api-versioning) for more details. ### Body (application/json) This endpoint expects an object. - `workflowId` (string, required) — 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"` - `inputs` (list of WorkflowRunsBatchPostRequestBodyContentApplicationJsonSchemaInputsItems, 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. - `version` (string, optional) — 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. - `priority` (integer, optional, default: 90) — An optional value used to determine the relative order of WorkflowRuns when rate limiting is in effect. Lower values will be prioritized before higher values. Defaults to 90 if not specified. ## Response ### 200 Successfully queued batch workflow run - `success` (boolean, required) — Indicates whether the batch request was successfully accepted and queued. `true` signifies success. - `batchId` (string, required) — 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 Bad Request - `success` (boolean, optional) - `error` (string, optional) — Error message ### 401 Unauthorized Error Unauthorized - `success` (boolean, optional) - `error` (string, optional) — Error message ### 404 Not Found Error Not Found - `success` (boolean, optional) - `error` (string, optional) — Error message ## Types ### WorkflowRunsBatchPostRequestBodyContentApplicationJsonSchemaInputsItems - `file` (BatchWorkflowRunFileInput, optional) — The file to be processed. Either `file` or `rawText` must be provided for each input. - `rawText` (string, optional) — 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` (map from string to any, optional) — 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. - `secrets` (WorkflowRunsBatchPostRequestBodyContentApplicationJsonSchemaInputsItemsSecrets, optional) — An optional object containing secrets to be used by processors within the workflow for this specific run. ### BatchWorkflowRunFileInput Input file for batch workflow runs. - `fileName` (string, optional) — 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. - `fileUrl` (string, optional) — A URL where the file can be downloaded from. If you use presigned URLs, we suggest a slightly longer expiration time, ideally 30 minutes for a worst case scenario. One of a `fileUrl` or `fileId` must be provided. - `fileId` (string, optional) — Extend's internal ID for the file. It will always start with `file_`. One of a `fileUrl` or `fileId` must be provided. You can view a file ID from the Extend UI, for instance from running a parser or from a previous file creation. If you provide a `fileId`, any parsed data will be reused. Example: `"file_Zk9mNP12Qw4yTv8BdR3H"` ### WorkflowRunsBatchPostRequestBodyContentApplicationJsonSchemaInputsItemsSecrets An optional object containing secrets to be used by processors within the workflow for this specific run. ## Examples **Request** ```json { "workflowId": "workflow_id_here", "inputs": [ {} ] } ``` **Response** ```json { "success": true, "batchId": "batch_zyx987" } ```