Skip to main content
Batch executions allow you to run an agent many times with different inputs in a single operation. Instead of triggering executions one-by-one, you upload a CSV of inputs, configure scheduling parameters, and let the platform handle the rest.

Bulk Input

Upload a CSV to define inputs for each execution

Controlled Scheduling

Stagger executions with configurable concurrency and intervals

Lifecycle Management

Pause, resume, or cancel an entire batch at once

Progress Tracking

Monitor how many executions have been triggered, are pending, or cancelled

​
How It Works

A batch is a container that groups multiple scheduled executions together. When you create a batch, you provide:
  1. A CSV file where each row defines the inputs for a single execution
  2. A batch configuration that controls when and how fast executions are triggered
The platform creates one scheduled execution per CSV row and staggers them over time according to your configuration. Each scheduled execution is triggered automatically when its scheduled time arrives, creating an actual agent execution.

​
Creating a Batch

Creating a batch is a guided process in the platform, broken into four steps.
1

Upload CSV

Upload a CSV file containing your execution data. Each row represents one execution, and each column contains data that will be mapped to agent inputs, profiles, or metadata.The CSV must include a header row. The platform parses it client-side using Papa Parse and validates that the file has consistent column counts.
You can drag and drop a CSV file or click to browse. The platform accepts standard comma-separated CSV files.
2

Map Columns

Map each CSV column to one of the following field types:
Mapping TypeDescription
Input VariableMaps to one of the agent workflow’s defined input variables
Agent Profile NameOverrides the default agent profile for that row
MetadataAttaches arbitrary key-value metadata to the execution
SkipIgnores the column entirely
The platform auto-maps columns where the CSV header matches an input variable name (case-insensitive, with whitespace normalized to underscores). You can adjust mappings manually.
Column mappings are saved to your browser per agent. When you upload a new CSV with the same structure, your previous mappings are automatically restored.
Validation rules:
  • All required workflow input variables must be mapped
  • No duplicate mappings to the same field
  • At least one column must be mapped (not skipped)
  • Metadata fields must have names specified
3

Preview & Validate

Review a preview of the first 10 rows showing how your data maps to each field. Each row is validated and shows a status indicator:
  • Valid rows are ready for execution
  • Invalid rows display error tooltips explaining the issue
Fix any issues in your CSV and re-upload if needed before proceeding.
4

Configure Batch

Set the batch execution parameters:
ParameterDescription
Batch NameA descriptive name to identify this batch
Workflow VersionWhich version of the agent workflow to execute
Default Agent ProfileThe profile to use for rows that don’t specify one
Start TimeWhen to begin triggering executions
Max ConcurrentNumber of executions to trigger per batch interval
Batch IntervalSeconds to wait between each group of concurrent executions
If the start time is in the past or now, the batch begins immediately with a running status. If the start time is in the future, the batch is created with a pending status and will start automatically at the specified time.

​
Time-Based Batching

The scheduling system uses time-based batching to stagger execution start times and avoid overwhelming target systems or hitting rate limits. The formula is: 
For each item at index i:
  batchIndex = floor(i / maxConcurrent)
  executeAt  = startAt + (batchIndex * batchInterval seconds)

​
Example

With maxConcurrent = 5 and batchInterval = 60 seconds:
ItemsExecute At
Rows 0-4startAt (immediately)
Rows 5-9startAt + 60s
Rows 10-14startAt + 120s
Rows 15-19startAt + 180s
This means 5 executions are triggered every 60 seconds until all rows have been processed.
Choose your concurrency and interval settings based on the target system’s rate limits and your agent’s resource requirements. Start conservative and increase if needed.

​
Batch Lifecycle

Batches follow a strict state machine that controls how scheduled executions are processed.

​
Batch Statuses

StatusDescription
PendingBatch is created with a future start time. Waiting for the start time to arrive.
RunningActively triggering scheduled executions according to the batch interval.
PausedUser paused the batch. No new executions are triggered until resumed.
CompletedAll scheduled executions in the batch have been triggered.
CancelledBatch was cancelled. Remaining pending executions will not be triggered.

​
Scheduled Execution Statuses

Each item within a batch has its own status:
StatusDescription
PendingWaiting for its scheduled execute time to arrive
TriggeredThe execution has been created and started
CancelledThis specific scheduled execution was cancelled

​
Managing Batches

Once created, you can manage batches from the Batch tab on the agent page.

​
Viewing Batches

The batch list shows all batches for the agent with:
  • Name and current status
  • Progress bar showing triggered vs. total executions
  • Created and started timestamps
  • Action buttons for lifecycle management

​
Pause

Pausing a batch stops new executions from being triggered. Executions that have already been triggered continue running. Use pause when you need to temporarily halt a batch without losing progress.

​
Resume

Resuming a paused batch recalculates the execution schedule from the current time and continues triggering remaining pending executions.

​
Cancel

Cancelling a batch permanently stops it. Pending scheduled executions are cancelled and will not be triggered. Executions already in progress are not affected.
Cancelling a batch is irreversible. Already-triggered executions will continue running, but no new executions will start.

​
Viewing Scheduled Executions

Click View Scheduled Executions on a batch card to see all individual scheduled executions. From here you can:
  • See the status of each scheduled execution
  • View when each execution is scheduled to run
  • Cancel or reschedule individual executions

​
Progress Tracking

Each batch tracks aggregate statistics across its scheduled executions:
MetricDescription
TotalTotal number of scheduled executions in the batch
PendingExecutions waiting to be triggered
TriggeredExecutions that have been started
CancelledExecutions that were cancelled
The progress bar on each batch card shows triggered / total as a percentage, giving you an at-a-glance view of batch completion.

​
Best Practices

​
1. Start with Small Batches

Test your configuration with a small CSV (5-10 rows) before running large batches. This lets you verify column mappings, input formatting, and agent behavior.

​
2. Use Conservative Concurrency

Start with low maxConcurrent values and increase gradually. Running too many concurrent executions can overwhelm target systems or trigger rate limiting.

​
3. Leverage Saved Mappings

If you regularly run batches with the same CSV structure, your column mappings are saved automatically per agent. This speeds up repeat batch creation.

​
4. Combine with Profile Pools

For large batches, use Profile Pools to automatically rotate agent profiles across executions. This distributes load across credentials and avoids concurrent use conflicts.

​
5. Monitor with Webhooks

For large batches, set up webhooks to receive real-time notifications as individual executions complete, fail, or require attention. This is more efficient than polling the batch status.

Execution Statuses

Understand individual execution lifecycle states

Agent Profiles

Configure profiles and profile pools for batch executions

Webhooks

Set up real-time notifications for execution events

API Reference

View batch execution API endpoints