Campaigns API

See also: Runs concept and configuration for what this API powers, when to call it, and how it is configured.

Campaigns define recurring batch execution configurations. Each campaign targets a decision flow and customer segment, with schedule, volume, and file settings. Campaign runs are individual execution instances.

See the Campaigns feature page for UI guidance on creating and managing campaigns.

Base path

/api/v1/runs

List campaigns

GET /api/v1/runs

Returns a paginated list of campaigns with latest run info.

Query parameters

Parameter	Required	Type	Description
`limit`	No	integer	Max results per page. Default `50`, max `200`.
`offset`	No	integer	Records to skip. Default `0`.

Response `200`

{
  "runs": [
    {
      "id": "camp_001",
      "name": "Weekly High-Value Campaign",
      "status": "active",
      "scheduleType": "weekly",
      "scheduleDayOfWeek": 1,
      "scheduleTime": "09:00",
      "scheduleTimezone": "America/New_York",
      "decisionFlowName": "Q1 Cross-Sell",
      "segmentName": "High Value Customers",
      "segmentCustomerCount": 4521,
      "runCount": 3,
      "lastRunAt": "2026-03-15T14:00:00.000Z",
      "latestRun": {
        "id": "run_003",
        "status": "completed",
        "runNumber": 3
      }
    }
  ],
  "total": 5
}

Create campaign

POST /api/v1/runs

Creates a new campaign configuration. Does not trigger execution — use the trigger endpoint to start a run.

Request body

Field	Required	Type	Description
`decisionFlowId`	Yes	string	Decision flow to execute
`segmentId`	Yes	string	Customer segment to target
`name`	No	string	Campaign name (auto-generated if omitted)
`description`	No	string	Campaign purpose and notes
`status`	No	enum	`draft`, `active`, `paused`, `archived`. Default: `draft`
`scheduleType`	No	enum	`manual`, `daily`, `weekly`, `monthly`, `custom`. Default: `manual`
`scheduleDayOfWeek`	No	integer	0=Sun..6=Sat (for weekly)
`scheduleDayOfMonth`	No	string	1-28 or `last_working_day` (for monthly)
`scheduleTime`	No	string	HH:mm format. Default: `09:00`
`scheduleTimezone`	No	string	IANA timezone identifier (for example `America/New_York`). Default: UTC.
`scheduleCron`	No	string	Cron expression, used only when `scheduleType` is `custom` (e.g., `0 9 * * 1`).
`frequencyCaps`	No	object	`{ maxTotalPerRun?, maxPerOffer?, maxPerChannel? }` — accepted and stored, but not currently enforced by the batch executor. Use a Contact Policy `frequency_cap` rule instead for actual capping.
`fileConfig`	No	object	`Run.fileConfig` v2 — the campaign’s outbound-file config that the batch executor reads for every file-mode channel in the run: `{ destinationConnectorId?, destinationPath?, format?, delimiter?, includeHeader?, namingPattern?, columns?: {name, source, transforms?}[] }`. Validated permissively (`validateRunFileConfig`); an omitted/empty/legacy value is accepted. See File Output Configuration.
`channelIds`	No	string[]	Batch channel IDs to target (empty = all batch channels)

When status is active and scheduleType is not manual, the campaign is picked up by the /api/v1/cron/campaign-scheduler route (5-minute cadence in the in-process maintenance scheduler) and a campaign run is triggered automatically once the schedule is due — see Schedule Configuration for the full firing semantics.

Example request

{
  "decisionFlowId": "df_001",
  "segmentId": "seg_001",
  "name": "Weekly High-Value Campaign",
  "status": "active",
  "scheduleType": "weekly",
  "scheduleDayOfWeek": 1,
  "scheduleTime": "09:00",
  "scheduleTimezone": "America/New_York",
  "channelIds": ["ch_batch_email"],
  "fileConfig": {
    "destinationConnectorId": "conn_s3_outbound",
    "destinationPath": "campaigns/{{date}}/",
    "format": "csv",
    "columns": [
      { "name": "email", "source": "contact.email", "transforms": [{ "op": "lowercase" }] },
      { "name": "offer", "source": "offer.name" },
      { "name": "tier", "source": "attribute.loyalty_tier", "transforms": [{ "op": "uppercase" }] }
    ]
  }
}

The fileConfig above is the campaign-owned file output (Run.fileConfig v2) — it drives the file every file-mode channel in the campaign writes. See File Output Configuration for the full field and column-source reference.

Response `201`

Returns the created campaign object.

Update campaign

PUT /api/v1/runs/:id

Updates campaign configuration. Accepts any combination of the following fields: name, description, status, scheduleType, scheduleDayOfWeek, scheduleDayOfMonth, scheduleTime, scheduleTimezone, scheduleCron, frequencyCaps, fileConfig, channelIds, decisionFlowId, segmentId.

Unlike most update endpoints, PUT allows changing decisionFlowId and segmentId to retarget a campaign to a different decision flow or customer segment.

Delete campaign

DELETE /api/v1/runs/:id

Deletes the campaign and all its runs. Requires admin role.

Get campaign detail

GET /api/v1/runs/:id

Returns the campaign config with the last 10 runs, resolved offer names in summaries, and enriched per-customer results.

Trigger a campaign run

POST /api/v1/runs/:id/campaign-runs

Creates and starts a new campaign run. The run is enqueued for processing by the worker tier, with inline fallback when the queue is unavailable. The run is reserved under a FOR UPDATE lock on the campaign, so the endpoint is idempotent under concurrency: two racing triggers (a double-click, a retry, or a manual trigger coinciding with a scheduled tick) can’t each mint a run and each execute the full segment. A trigger issued while a run for the campaign is already pending or running returns that in-flight run with 200 (below) rather than starting a second.

Response `201` (new run created)

{
  "id": "crun_001",
  "campaignId": "camp_001",
  "runNumber": 4,
  "triggeredBy": "manual",
  "status": "pending",
  "createdAt": "2026-03-22T09:00:00.000Z"
}

Response `200` (a run is already in flight)

Returns the existing pending/running campaign run unchanged — no second execution is started.

{
  "id": "crun_000",
  "campaignId": "camp_001",
  "runNumber": 3,
  "triggeredBy": "manual",
  "status": "running",
  "createdAt": "2026-03-22T08:55:00.000Z"
}

List campaign runs

GET /api/v1/runs/:id/campaign-runs

Returns execution history for a campaign, ordered by run number descending (max 50).

Each run’s summary.fileOutputs[].filePath is a retrievable download — GET /api/v1/runs/artifacts/:id when it wasn’t uploaded to S3. See Retrieving Generated Files.

Execute a run inline (background)

POST /api/v1/runs/execute-inline

Fire a run execution in the background and return immediately. The endpoint dispatches the batch executor without awaiting it — the HTTP response is sent before the batch starts producing output, and any per-run failure is recorded in the run’s status and logs rather than surfaced to the caller. This endpoint is for inline triggers from a single-tenant dev environment or a backup path when the worker tier is degraded. Production triggering should use POST /api/v1/runs/:id/campaign-runs so the run gets a campaign-run record, retry semantics, and DLQ visibility.

Request Body

string

required

Identifier of the run record that the executor will update with status, startedAt, and completedAt.

string

required

Decision flow to execute against.

string

required

Customer-segment view name. The executor reads from this Postgres view to enumerate target customers.

Response

Status 200.

{
  "status": "executing",
  "runId": "run_42"
}

The response is sent the moment the executor is dispatched. The caller monitors progress by polling GET /api/v1/runs/:id.

Status codes

Code	When
200	Executor dispatched (returned immediately, before completion)
400	Missing `runId`, `decisionFlowId`, or `segmentViewName`
401 / 403	Caller is not authenticated, or not `admin` / `editor`
404	`runId`, `decisionFlowId`, or `segmentViewName` does not resolve to a Run / Decision Flow / Segment owned by the caller’s tenant — all three are validated before dispatch, so an unknown or foreign id fails fast instead of starting a run that fails asynchronously

Roles

admin, editor.

Errors raised by the batch executor after the response is sent are logged but never surfaced to the caller. The run record’s status and error fields are the source of truth for outcome — poll GET /api/v1/runs/:id to see the final state.

Campaign statuses

Status	Description
`draft`	Created but not yet active
`active`	Live — scheduled runs execute automatically
`paused`	Temporarily disabled
`archived`	Retired, preserved for history

Run statuses

Status	Description
`pending`	Waiting for worker to pick up
`running`	Processing customers
`completed`	All customers processed
`completed_with_errors`	Finished but something went wrong for a subset of the run — a delivery failure or a per-customer decisioning error. See `error` and `results.summary.errorCount` on the run/campaign-run record.
`failed`	Unrecoverable error

Role requirements

Method	Minimum role
GET (list/detail)	`viewer`
POST (create/trigger)	`editor`
PUT (update)	`editor`
DELETE	`admin`

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Base path

List campaigns

Query parameters

Response `200`

Create campaign

Request body

Example request

Response `201`

Update campaign

Delete campaign

Get campaign detail

Trigger a campaign run

Response `201` (new run created)

Response `200` (a run is already in flight)

List campaign runs

Execute a run inline (background)

Request Body

Response

Status codes

Roles

Campaign statuses

Run statuses

Role requirements

​Base path

​List campaigns

​Query parameters

​Response 200

​Create campaign

​Request body

​Example request

​Response 201

​Update campaign

​Delete campaign

​Get campaign detail

​Trigger a campaign run

​Response 201 (new run created)

​Response 200 (a run is already in flight)

​List campaign runs

​Execute a run inline (background)

​Request Body

​Response

​Status codes

​Roles

​Campaign statuses

​Run statuses

​Role requirements

Base path

List campaigns

Query parameters

Response `200`

Create campaign

Request body

Example request

Response `201`

Update campaign

Delete campaign

Get campaign detail

Trigger a campaign run

Response `201` (new run created)

Response `200` (a run is already in flight)

List campaign runs

Execute a run inline (background)

Request Body

Response

Status codes

Roles

Campaign statuses

Run statuses

Role requirements