Campaign Runs

A run represents a single dispatch of a published campaign to an audience.

Runs are generated in two ways:

• Scheduled Runs: The campaign's initial run, created automatically when you publish via POST /schedule-jobs or POST /send-jobs.
• On-Demand Runs: Additional runs triggered manually or programmatically via POST /campaigns/:id/runs. This is used for rolling enrollment cycles, follow-up sends, or triggering a new direct mail drop for a refreshed audience.

This page documents how to retrieve the history of a campaign's runs and how to trigger new ones via the API.

Base URL: https://api.experiture.ai/public/v1

List Campaign Runs

Returns the most recent runs for a campaign, including their current execution status. Useful for operational dashboards, polling for completion, or retrieving generated export files.

GET /campaigns/:id/runs?limit=25
Authorization: Bearer <token>

Required scope: campaigns:read

Path parameters

Query parameters

Response — 200 OK

{
  "success": true,
  "data": {
    "campaignId": "4130bada-9264-465f-bc0c-a26bebcfcc81",
    "name": "Spring Re-engagement Direct Mail",
    "channel": "direct_mail",
    "manifestId": "33333333-3333-3333-3333-333333333333",
    "touchpointId": 123,
    "runs": [
      {
        "runId": "5e5e5e5e-5e5e-5e5e-5e5e-5e5e5e5e5e5e",
        "scheduleRunId": "5e5e5e5e-5e5e-5e5e-5e5e-5e5e5e5e5e5e",
        "scheduleId": "44444444-4444-4444-4444-444444444444",
        "manifestId": "33333333-3333-3333-3333-333333333333",
        "touchpointId": 123,
        "channel": "direct_mail",
        "runKind": "on_demand",
        "runStatus": "enqueued",
        "requestSource": "api",
        "requestedAt": "2026-05-09T13:40:11.000Z",
        "unitCount": 17480,
        "packageStatus": "ready",
        "package": {}
      }
    ]
  }
}

If the campaign has no manifest yet (never finalized) the response returns runs: [].

Run object fields

Trigger a New Run

Requests a new run against an already published campaign. For example, use this to drop another batch of a Direct Mail piece against an updated audience snapshot, to enqueue a rolling-enrollment cycle, or to trigger an on-demand re-send to a freshly-suppressed cohort.

POST /campaigns/:id/runs
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <uuid-v4>   (optional, 24-hour deduplication)

Required scope: campaigns:update

Path parameters

Request body

audience object

Response — 202 Accepted

{
  "success": true,
  "data": {
    "runRequestId": "7c3e6a2a-1d4f-49ab-aabb-ccccccccdddd",
    "runId": "5e5e5e5e-5e5e-5e5e-5e5e-5e5e5e5e5e5e",
    "scheduleRunId": "5e5e5e5e-5e5e-5e5e-5e5e-5e5e5e5e5e5e",
    "campaignId": "4130bada-9264-465f-bc0c-a26bebcfcc81",
    "scheduleId": "44444444-4444-4444-4444-444444444444",
    "manifestId": "33333333-3333-3333-3333-333333333333",
    "touchpointId": 123,
    "channel": "direct_mail",
    "status": "pending",
    "requestSource": "api",
    "requestKind": "on_demand",
    "dueAt": "2026-05-09T13:40:11.000Z",
    "requestedAt": "2026-05-09T13:40:11.000Z"
  }
}

The request is queued asynchronously. To observe the run's progress, poll GET /campaigns/:id/runs and read the matching runId's runStatus property.

Errors

Run Metadata Reference

Run Kinds

runKind on a run object records how the run originated. It is a response field — you don't set it directly. (The requestKind you send on POST /runs is a separate field, and in v1 only accepts on_demand.)

Run Status

A run progresses through these states, visible on runs[].runStatus:

A failed or cancelled run does not block additional run requests — but it does count toward the 5-active-request backpressure limit until the worker clears it.

Request Sources

requestSource records who or what created the run, so downstream audit reports can distinguish them:

Run Lifecycle Diagram

Whether a run is created automatically by a schedule or manually via the API, the execution lifecycle is identical.

POST /schedule-jobs                  POST /campaigns/:id/runs
       │                                       │
       │  (initial, finalizes asynchronously)  │  (additional, on a published campaign)
       ▼                                       ▼
   run #0  ─────────►  enqueued  ────►  package: pending → assembling → ready → handed_off
       │
       └──► failed                  ─────►  package: failed (failureKind populated)

Advanced: Execution Packages & Exports

Unlike digital channels (Email, SMS) which are event-driven, channels like Direct Mail require the platform to generate secure export files (PDFs, USPS manifest CSVs, Intelligent Mail Barcodes).

These files are bundled into an Execution Package. When querying /campaigns/:id/runs for a campaign that generates physical artifacts, the response will include a package object containing secure URIs to these files.

Package Status

If a package is generated, it goes through its own lifecycle independent of the overall run status:

failureKind is one of upstream_execution, finalizer_aggregation, handoff, artifact_write, provider.

Package Object Fields

Artifact Object Fields

Each entry in the package.artifacts[] array represents a distinct file generated for the run:

See Also

• Schedule & Send — create the campaign's first run via the schedule/send job endpoints
• Status & Metrics — surface-level execution state and pipeline counts
• Preflight — validate readiness before creating a new run
• Campaign Reporting Guide — patterns for ingesting delivery events into BI