Flows

Running flows in batch

Use Batch to run a Flow once for each Record in a selected Record type. Runtype submits the work 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.

Run a batch

To run a Flow for every Record of a 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.

The dashboard submits the batch for asynchronous processing. Each Record becomes one Flow execution. Access the current Record with _record; use {{_record.metadata.FIELD_NAME}} to read metadata.

Get data into a batch

The dashboard runs batches over saved Records. Create or import external data as Records before you run a batch.

  1. On the Records page, create or import the Records to process.
  2. Return to the Flow, open the Batch tab, and select the Record type.

You can import Records from a CSV file. For programmatic control over filters or limits, use the batch API or SDK instead of the Batch tab.

The batch API accepts data in two forms, and one request can carry both:

  • recordIds: the IDs of saved Records to process.
  • records: inline records that are never written to the Records table. Each entry has a name, a type, and a metadata object of any shape, which the Flow reads as {{_record.metadata.*}}.

A request can target a saved Flow (flowId), an inline Flow definition (flowDefinition), or an Agent (agentId), and can pass inputs and a messages seed to every record execution. When the target is an Agent, each saved Record supplies its conversation in metadata.messages; an inline record reaches the Agent only when its type is _agent_eval or _agent_schedule and metadata.messages carries the conversation. Any other inline record type fails for that record. For the full request body, see the POST /v1/batch/flow entry in the API reference.

Monitor batch runs

After you start a batch, follow these steps to monitor its status:

  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.

Batches run asynchronously. You can close the dashboard after you submit a batch.

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.

To export the filtered log view, click Export and choose Export as CSV or Export as JSON.

Handle failures

If a Record fails, follow these steps:

  1. Open the failed batch entry in Logs.
  2. Review the error, Record metadata, and step details.
  3. Fix the Flow or the affected Record.
  4. Run the batch again.

The dashboard does not provide a separate retry control for failed Records. To rerun only selected failed Records, submit their Record IDs through the batch API.

Understand batch limits

The dashboard supports up to 50,000 Records in one batch request. Workspace execution quotas can reject a batch before processing if the requested count exceeds available capacity. For large batches, split the Records into smaller groups.

Manage batch costs

A batch of 1,000 Records creates 1,000 Flow executions. Model and built-in tool calls drive usage cost. Review Usage in Settings before a large batch. Set a spending cap in Billing under Settings.

Schedule batches

To repeat a Flow on a schedule, follow these steps:

  1. Open Schedules.
  2. Create a schedule for the Flow.
  3. Target a Record type, specific Record IDs, or a filter.
  4. Set the schedule frequency.

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 usage in Settings before you submit a large batch.
  • Use the batch API when you need Record filters, limits, or selected Record IDs.
  • Fix input or Flow errors before you rerun failed Records.

Next steps

Continue with these guides: