Runs represent batch executions of a decision flow against a customer segment. When a run is created, it is enqueued for processing by worker pods via BullMQ. Each run tracks its status, progress, and results.
Base path
List runs
Returns a paginated list of runs for the current tenant, ordered by creation date (newest first). Each run includes the associated decision flow name and segment details.
Query parameters
| Parameter | Required | Type | Description |
|---|
limit | No | integer | Maximum results per page. Default 50, max 200. |
offset | No | integer | Number of records to skip. Default 0. |
This endpoint uses offset-based pagination instead of cursor-based pagination.
Response 200
{
"runs": [
{
"id": "run_001",
"tenantId": "t_001",
"name": "Credit Card NBA x High Value Customers",
"decisionFlowId": "df_001",
"segmentId": "seg_001",
"status": "completed",
"decisionFlowName": "Credit Card NBA",
"decisionFlowKey": "credit-card-nba",
"segmentName": "High Value Customers",
"segmentCustomerCount": 4521,
"createdAt": "2026-03-15T14:00:00.000Z",
"updatedAt": "2026-03-15T14:05:00.000Z"
}
],
"total": 12
}
Run statuses
| Status | Description |
|---|
pending | Run created, waiting to be picked up by a worker. |
running | Worker is actively processing the segment. |
completed | All customers in the segment have been processed. |
failed | Run encountered an error and stopped. |
Create a run
Creates a new batch run and enqueues it for processing. The run name defaults to "{flow name} x {segment name}" if not provided.
Request body
| Field | Required | Type | Description |
|---|
decisionFlowId | Yes | string | Decision flow to execute. |
segmentId | Yes | string | Customer segment to process. |
name | No | string | Custom run name. |
Validation checks
Before creating the run, the API validates:
- The decision flow exists and belongs to the tenant.
- The segment exists and has a materialized view (i.e., it has been saved with filters).
- At least one batch-compatible channel exists (delivery mode:
file, integration, or manual).
Example request
{
"decisionFlowId": "df_001",
"segmentId": "seg_001",
"name": "Q1 Campaign Run"
}
Response 201
{
"id": "run_001",
"tenantId": "t_001",
"name": "Q1 Campaign Run",
"decisionFlowId": "df_001",
"segmentId": "seg_001",
"status": "pending",
"createdAt": "2026-03-15T14:00:00.000Z",
"updatedAt": "2026-03-15T14:00:00.000Z"
}
Error codes
| Code | Reason |
|---|
400 | Missing decisionFlowId or segmentId. |
400 | Segment has no materialized view. |
400 | No batch-compatible channels found. |
404 | Decision flow or segment not found. |
Role requirements
| Method | Minimum role |
|---|
| GET | viewer |
| POST | editor |
