Skip to main content

​
Overview

A campaign defines a recurring batch execution configuration. Each campaign targets a Decision Flow and a customer Segment, with schedule settings, volume constraints, and file output configuration. When a campaign runs, it creates a campaign run — an individual execution instance that processes every customer in the segment through the Decision Flow. 
Campaign (config + schedule) → Campaign Run #1 → Campaign Run #2 → ...

​
Campaign vs Campaign Run

ConceptWhat It IsLifecycle
CampaignSchedule config, volume limits, file output settings, target flow + segmentPersistent — draft, active, paused, archived
Campaign RunIndividual execution of a campaignTransient — pending → running → completed/failed

​
How Campaigns Work

1

Create campaign

Select a Decision Flow, target segment, schedule, volume constraints, and file output config.
2

Configure schedule

Choose manual, daily, weekly (pick day), or monthly (pick day or last working day). Set time and timezone.
3

Set volume constraints

Optionally limit max recommendations per run, per offer, or per channel.
4

Configure file output

Choose format (CSV/JSON), select columns, enable personalization, set destination (download or S3).
5

Run

Click “Run Now” for manual execution, or activate the campaign for scheduled runs.
6

Review run history

Each execution appears as a numbered run with full results, offer breakdown, and file outputs.

​
Schedule Configuration

Schedule TypeDescriptionConfig Fields
manualTriggered manually via “Run Now” button or APINone
dailyRuns every day at a specified timescheduleTime, scheduleTimezone
weeklyRuns once per week on a specific dayscheduleDayOfWeek (0=Sun..6=Sat), scheduleTime, scheduleTimezone
monthlyRuns once per month on a specific dayscheduleDayOfMonth (1-28 or last_working_day), scheduleTime, scheduleTimezone

​
Volume Constraints

Control the scale of each run to manage campaign costs and audience fatigue.
ConstraintTypeDescription
maxTotalPerRunnumberMaximum total recommendations across all offers
maxPerOffernumberMaximum recommendations per individual offer
maxPerChannelnumberMaximum recommendations per delivery channel
When a volume constraint is reached, remaining customers are skipped gracefully. The run summary reports both the total segment size and the number actually processed.

​
File Output Configuration

Configure how batch output files are generated for file-mode and manual channels.
FieldTypeDefaultDescription
formatenumcsvOutput format: csv or json
columnsstring[]["customer_id", "offer_name", "channel", "score", "creative"]Columns to include in the output file
includePersonalizationbooleanfalseWhether to include per-customer personalization fields
destinationenumdownloadWhere to place files: download (virtual path) or s3 (upload to S3)
s3Pathstring—S3 path template, e.g. s3://bucket/campaigns/{campaign_id}/{run_date}/

​
Available Columns

ColumnDescription
customer_idCustomer identifier
offer_nameName of the recommended offer
offer_idOffer identifier
channelDelivery channel name
creativeCreative/treatment name
scorePropensity score (0-1)
rankRank position within customer’s recommendations
categoryOffer category (business objective)
priorityOffer priority
personalizationPer-customer computed values (requires includePersonalization: true)

​
Batch Channels

Only channels with file, integration, or manual delivery mode are included in batch campaigns. API (real-time) channels are excluded because batch runs produce file-based output. When creating a campaign, you can optionally select specific batch channels. If no channels are selected, all batch-compatible channels are included.

​
Campaign Status

StatusDescription
draftCampaign created but not yet active
activeCampaign is live — scheduled runs will execute automatically
pausedCampaign is temporarily disabled — no scheduled runs
archivedCampaign is retired — preserved for history

​
Campaign Run Status

StatusDescription
pendingRun created, waiting for worker to pick it up
runningCurrently processing customers through the Decision Flow
completedAll customers processed successfully
completed_with_errorsProcessing finished but some deliveries failed (e.g. S3 upload)
failedExecution encountered an unrecoverable error

​
Run Results

After a campaign run completes, results are available at three levels:

​
Overall Statistics

MetricDescription
totalCustomersNumber of customers in the target segment
processedNumber of customers processed
recommendedCustomers who received at least one offer
avgLatencyMsAverage per-customer processing time

​
Summary Breakdown

{
  "offerBreakdown": {
    "Premium Credit Card": 12450,
    "Personal Loan": 8320,
    "Savings Account": 15680
  },
  "channelBreakdown": {
    "Email": 22100,
    "Push": 9850,
    "In-App": 4500
  },
  "rejectionSummary": {
    "qualification": 3200,
    "contactPolicy": 1800,
    "budgetExhausted": 450
  },
  "fileOutputs": [
    {
      "channelName": "Batch Email",
      "filePath": "s3://bucket/campaigns/camp_123/2026-03-10/email.csv",
      "rowCount": 22100,
      "sizeBytes": 1843200
    }
  ]
}

​
Per-Customer Results

Each customer’s result shows the selected offers with scores: 
{
  "customerId": "SBX-000001",
  "selections": [
    { "offerId": "...", "offerName": "Premium Credit Card", "score": 0.85, "rank": 1 },
    { "offerId": "...", "offerName": "Personal Loan", "score": 0.72, "rank": 2 }
  ],
  "latencyMs": 32
}
Offer IDs in the summary and per-customer results are automatically resolved to human-readable names in the API response.

​
API Reference

​
Create Campaign

POST /api/v1/runs
Content-Type: application/json

{
  "name": "Weekly High-Value Campaign",
  "description": "Target high-income members every Monday",
  "decisionFlowId": "df_q1_campaign",
  "segmentId": "seg_high_value",
  "status": "active",
  "scheduleType": "weekly",
  "scheduleDayOfWeek": 1,
  "scheduleTime": "09:00",
  "scheduleTimezone": "America/New_York",
  "volumeConstraints": {
    "maxTotalPerRun": 10000,
    "maxPerOffer": 500
  },
  "fileConfig": {
    "format": "csv",
    "columns": ["customer_id", "offer_name", "channel", "score", "creative"],
    "includePersonalization": true,
    "destination": "s3",
    "s3Path": "s3://bucket/campaigns/{campaign_id}/{run_date}/"
  },
  "channelIds": ["ch_batch_email", "ch_manual"]
}

​
Update Campaign

PUT /api/v1/runs/:id
Content-Type: application/json
Accepts any combination of campaign fields to update.

​
Trigger Run

POST /api/v1/runs/:id/campaign-runs
Creates and starts a new campaign run. Returns the run record with status pending.

​
List Campaign Runs

GET /api/v1/runs/:id/campaign-runs
Returns the execution history for a campaign, ordered by run number descending.

​
Get Campaign Detail

GET /api/v1/runs/:id
Returns the campaign config plus the last 10 runs, with offer names resolved in summaries and per-customer results.

​
List Campaigns

GET /api/v1/runs?limit=50&offset=0
Returns all campaigns with latest run status.

​
UI Walkthrough

1

Navigate to Campaigns

Go to Campaigns in the sidebar (was “Runs”).
2

Create campaign

Click + New Campaign. Configure the decision flow, segment, schedule, volume constraints, batch channels, and file output settings.
3

Trigger a run

Select a campaign and click Run Now to trigger manual execution.
4

Monitor run history

Expand individual runs in the history to see stats, offer breakdown, and file outputs.

​
Next Steps

Dashboards

Monitor campaign performance and batch results.

Decision Flows

Configure the decisioning pipeline that campaigns execute.