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?.
• 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.

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:

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:

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:

{
  "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.

For the full request body, see 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:

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. 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:

For other request limits, see 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.

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: diagnose failed Records and rerun a batch.
• Automating batch processing: run a Flow on a schedule.
• What are Records?: understand Record-based batches.
• Working with logs: inspect and export execution details.
• Submit a batch flow execution: review the full batch request body.