> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Batch Executions
> Run your agent across multiple inputs in bulk with controlled scheduling and concurrency
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.
Upload a CSV to define inputs for each execution
Stagger executions with configurable concurrency and intervals
Pause, resume, or cancel an entire batch at once
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.
```mermaid theme={null}
graph LR
CSV[CSV Upload] --> Mapping[Column Mapping]
Mapping --> Config[Batch Configuration]
Config --> Batch[Batch Created]
Batch --> SE1[Scheduled Execution 1]
Batch --> SE2[Scheduled Execution 2]
Batch --> SE3[Scheduled Execution N...]
SE1 --> E1[Execution 1]
SE2 --> E2[Execution 2]
SE3 --> E3[Execution N...]
```
***
## Creating a Batch
Creating a batch is a guided process in the platform, broken into four steps.
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](https://www.papaparse.com/) 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.
Map each CSV column to one of the following field types:
| Mapping Type | Description |
| ---------------------- | ----------------------------------------------------------- |
| **Input Variable** | Maps to one of the agent workflow's defined input variables |
| **Agent Profile Name** | Overrides the default agent profile for that row |
| **Metadata** | Attaches arbitrary key-value metadata to the execution |
| **Skip** | Ignores 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
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.
Set the batch execution parameters:
| Parameter | Description |
| ------------------------- | ----------------------------------------------------------- |
| **Batch Name** | A descriptive name to identify this batch |
| **Workflow Version** | Which version of the agent workflow to execute |
| **Default Agent Profile** | The profile to use for rows that don't specify one |
| **Start Time** | When to begin triggering executions |
| **Max Concurrent** | Number of executions to trigger per batch interval |
| **Batch Interval** | Seconds 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:
| Items | Execute At |
| ---------- | ----------------------- |
| Rows 0-4 | `startAt` (immediately) |
| Rows 5-9 | `startAt + 60s` |
| Rows 10-14 | `startAt + 120s` |
| Rows 15-19 | `startAt + 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
```mermaid theme={null}
graph TB
pending[Pending]
running[Running]
paused[Paused]
completed[Completed]
cancelled[Cancelled]
pending --> running
pending --> cancelled
running --> paused
running --> completed
running --> cancelled
paused --> running
paused --> cancelled
style completed fill:#dcfce7
style cancelled fill:#fef3c7
style running fill:#dbeafe
style pending fill:#e0e7ff
style paused fill:#fde68a
```
| Status | Description |
| ------------- | -------------------------------------------------------------------------------- |
| **Pending** | Batch is created with a future start time. Waiting for the start time to arrive. |
| **Running** | Actively triggering scheduled executions according to the batch interval. |
| **Paused** | User paused the batch. No new executions are triggered until resumed. |
| **Completed** | All scheduled executions in the batch have been triggered. |
| **Cancelled** | Batch was cancelled. Remaining pending executions will not be triggered. |
### Scheduled Execution Statuses
Each item within a batch has its own status:
| Status | Description |
| ------------- | ------------------------------------------------ |
| **Pending** | Waiting for its scheduled execute time to arrive |
| **Triggered** | The execution has been created and started |
| **Cancelled** | This 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:
| Metric | Description |
| ------------- | ------------------------------------------------- |
| **Total** | Total number of scheduled executions in the batch |
| **Pending** | Executions waiting to be triggered |
| **Triggered** | Executions that have been started |
| **Cancelled** | Executions 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](/fundamentals/profiles#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](/fundamentals/integrations/webhooks) to receive real-time notifications as individual executions complete, fail, or require attention. This is more efficient than polling the batch status.
***
## Related Resources
Understand individual execution lifecycle states
Configure profiles and profile pools for batch executions
Set up real-time notifications for execution events
View batch execution API endpoints