> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # Running flows in batch Use **Batch** to run a Flow once for each Record in a selected Record type. Runtype processes the batch asynchronously, so you can close the dashboard after the batch starts. ## When to use batch processing Use Batch when you need to: * Run one Flow against many Records. * Process data imported into Records. * Test a Flow against a consistent set of inputs. * Transform or enrich Records with one Flow. ## Before you begin Make sure that you have the following: * Saved Records of the type that you want to process. To create or import them, see [What are Records?](/user-guide/records/what-are-records). * A Flow that reads Record data from `_record`. In the Flow, read Record data with `{{_record.metadata.FIELD_NAME}}`. Replace `FIELD_NAME` with a key in the Record's metadata. Each Record becomes one Flow execution. ## Run a batch from the dashboard To run a Flow on the Records of one type, follow these steps: 1. On the **Flows** page, open the Flow. 2. Click **Run flow**. 3. Select the **Batch** tab. 4. In **Record Type**, select the type to process. 5. Click **Run on Records**. A confirmation message shows how many Records the batch includes, and the batch appears in **Logs**. The **Batch** tab processes at most the first 50,000 Records of the selected type. To process more, split the Records across Record types, or submit batches of Record IDs from the CLI or API. ## Monitor batch runs To check the status of a batch, follow these steps: 1. Open **Logs**. 2. In **Type**, select **Batch**. 3. In **Status**, select a status such as **Queued**, **Running**, **Completed**, **Failed**, or **Cancelled**. 4. Open a batch entry to inspect its Record details and execution logs. ## Review batch results Batch results include one row for each processed Record. Each row shows its status, execution details, and error information when the Record fails. Open a row to review Record metadata, output, and step results. The batch view also shows two costs: * **Blended**: the total model and tool cost of the batch, including calls that use your own provider keys. * **Runtype-funded**: the part of that cost that ran on Runtype-provided keys. A dash means that Runtype can't split the cost for this batch. The detail panel for a single Record shows the same two costs for that Record. To export the filtered log view, click **Export** and choose **Export as CSV** or **Export as JSON**. ## Run a batch from the CLI or API Use the CLI or API to process a specific set of Records, or Records that were never saved. Submitting a batch with an API key has these requirements: * Your plan is Growth or higher. On other plans, the API returns `402` with the code `BATCH_API_ACCESS_DENIED`. Run batches from the dashboard instead. * The API key has the `DISPATCH:*` permission. Without it, the API returns `403`. For key permissions, see [Authentication](/developer-guides/getting-started/authentication#permissions). The batch API and CLI don't filter Records for you. To process a subset, list the Records that you want by type or metadata, then submit their IDs. ### Submit with the CLI To submit a batch and wait for it to finish, run the following commands: ```bash runtype batch submit --flow YOUR_FLOW_ID --records record-ids.json runtype batch status YOUR_BATCH_ID --watch ``` Replace the following: * `YOUR_FLOW_ID`: the ID of the Flow to run. * `YOUR_BATCH_ID`: the batch ID that `runtype batch submit` prints. The `record-ids.json` file contains a JSON array of Record IDs, such as `["YOUR_RECORD_ID"]`. By default, `--watch` stops polling after 5 minutes, and the batch keeps running. To wait longer, add `--timeout` with a value in milliseconds. ### Submit with the API To submit a batch, send a request to `POST /v1/batch/flow`: ```bash curl https://api.runtype.com/v1/batch/flow \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "flowId": "YOUR_FLOW_ID", "recordIds": ["YOUR_RECORD_ID"] }' ``` Replace the following: * `YOUR_API_KEY`: your Runtype API key. * `YOUR_FLOW_ID`: the ID of the Flow to run. * `YOUR_RECORD_ID`: the ID of a saved Record to process. The response contains the batch ID and its status: ```json { "batchExecutionId": "YOUR_BATCH_ID", "status": "processing" } ``` To check progress, send `GET /v1/batch/status/YOUR_BATCH_ID` with the same `Authorization` header. A request can also include these fields: * `records`: inline records to process without saving them as Records. Each entry has a `name`, a `type`, and a `metadata` object that the Flow reads as `{{_record.metadata.*}}`. Give each entry a unique `name`, because batch results are keyed by name. One request can combine `recordIds` and `records`. * `inputs`: Flow input variables applied to every Record execution. Keys can't start with `_`, because that prefix is reserved for system variables. * `messages`: a conversation seed passed to every Record execution. Records don't share conversation history with one another. * `flowDefinition`: an inline Flow definition to run in place of `flowId`, without saving the Flow. * `agentId`: an Agent to run in place of a Flow. Each saved Record supplies its conversation in `metadata.messages`. Use saved Records with an Agent target. Inline records of your own types fail for an Agent target. The `options` object tunes how the batch runs. The API rejects unknown or out-of-range option keys when you submit the batch. | Option | Range | Default | | ------------------- | -------------------------- | ------------------------------------------------------------------- | | `maxRetries` | 0 to 10 retries per Record | 3 (batches started from the dashboard use 5) | | `timeoutMs` | 1,000 to 1,800,000 ms | 900,000 ms (15 minutes) per Record | | `recordConcurrency` | 1 to 150 | 8. At most 20 Records run at the same time, whatever value you set. | | `flowTimeoutMs` | 1,000 to 1,800,000 ms | No Flow-wide deadline | | `stepTimeoutMs` | 1,000 to 1,800,000 ms | No per-step deadline | | `modelOverride` | A model ID | None. When set, every prompt step in the batch uses this model. | For the full request body, see [Submit a batch flow execution](/api-reference/runtype-api/batch/submit-a-batch-flow-execution) in the API reference. ## Cancel a batch The dashboard doesn't have a control to cancel a batch. To stop a queued or running batch, run the following command: ```bash runtype batch cancel YOUR_BATCH_ID ``` Replace `YOUR_BATCH_ID` with the batch ID that the submit call returned. With the API, send `POST /v1/batch/cancel/YOUR_BATCH_ID`. Records that finished before you cancel keep their results. ## Handle failures To diagnose failed Records and rerun a batch, see [Handling batch failures](/user-guide/flows/handling-batch-failures). To rerun only selected Records, submit their Record IDs from the CLI or API. ## Understand batch limits Runtype rejects a batch before processing in these cases: | Limit | Response | What to do | | ------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | More than 50,000 Records in one request, across `recordIds` and `records` | `400` | Split the Records across several requests. | | More than 250,000 batch Records submitted by one user in one hour (UTC) | `429` | Wait for the next hour, then submit the batch again. | | Your monthly spend cap is reached | `402` | Raise the spend cap in **Settings > Billing**. | | The Flow has a step that batch can't run, such as a top-level `wait-until` or `crawl` step | `422` (`RUNTIME_LANE_INELIGIBLE`) | Remove or replace the step. For top-level `wait-until` or `crawl` steps, you can instead run the Flow per Record with `POST /v1/dispatch`. | For other request limits, see [Rate limits and usage](/user-guide/troubleshooting-faq/rate-limits-and-usage). ## Manage batch costs A batch of 1,000 Records creates 1,000 Flow executions. Model and built-in tool calls drive usage cost. Review **Settings > Usage** before a large batch. Set a spend cap in **Settings > Billing**. To check the cost of a finished batch from the CLI, run `runtype batch cost YOUR_BATCH_ID`. Add `--record YOUR_RECORD_ID` to check one Record. ## Schedule batches To run a Flow on Records at a set time, create a Schedule with **Input Source** set to **Records**. In **Records**, select a Record type and add filter conditions to limit the Records. To target a fixed set of Record IDs, use the API. For the steps, see [Automating batch processing](/user-guide/schedules/automating-batch-processing). ## Follow batch best practices Use these practices before you run a large batch: * Test the Flow with a small set of Records. * Confirm that each Record contains the metadata fields the Flow reads. * Review **Settings > Usage** before you submit a large batch. * Fix input or Flow errors before you rerun failed Records. ## Next steps Continue with these guides: * [Handling batch failures](/user-guide/flows/handling-batch-failures): diagnose failed Records and rerun a batch. * [Automating batch processing](/user-guide/schedules/automating-batch-processing): run a Flow on a schedule. * [What are Records?](/user-guide/records/what-are-records): understand Record-based batches. * [Working with logs](/user-guide/logs/working-with-logs): inspect and export execution details. * [Submit a batch flow execution](/api-reference/runtype-api/batch/submit-a-batch-flow-execution): review the full batch request body.