---
name: plungeai-campaigns
description: "Run a list to completion on PlungeAI: the campaign ledger (claim/complete/fail/retry over data-table-agent), the campaign-config block (list source, cycle, cadence, retries, delivery), and how a campaign keeps going via cron or self-scheduling runAgain. Use when the user wants to process every row of a table on a cadence, run a batch job until a list is drained, or build a continuous monitor over a fixed set of items. There is no dedicated public API/MCP tool for this — author it in Studio with `plungeai-campaign-agent`, or as a plain workflow using the operations documented here; for the pipeline steps themselves use `plungeai-workflows`."
---

# PlungeAI Campaigns — running a list to completion

A campaign claims a list of items and works through them with per-item retries on
a repeating cadence, until the cycle is drained — the pattern behind "check every
row in this table weekly" or "watch these 50 URLs continuously." Its runtime is the
**campaign ledger**: a small set of `agent: data-table-agent` operations
(claim/complete/fail/release/status) that a CNL `type: batch` task with
`ledger: campaign` calls automatically.

## Prerequisites

- A self-service `ozk_` API key from **Dashboard → One API → Keys**
  (https://dashboard.plungeai.com) if you're calling the platform directly, or
  build the pipeline in Ocean Studio.
- **This capability has a thin public surface, by design honesty:** neither
  `https://api.plungeai.com` nor `https://mcp.plungeai.com/v1` exposes a dedicated
  campaign-management route or MCP tool today. The supported path is Studio's
  **`plungeai-campaign-agent`** kind (CNL + a `campaign-config` block); everything
  below is real, source-grounded detail for reading, extending, or hand-building a
  campaign pipeline as an ordinary workflow.

## Discover the pieces

The items a campaign processes still come from ordinary discovery — never guess an
agent id for the per-item work: `plungeai_list_agents {search: "<what each item
needs done>"}`. `data-table-agent` itself is a registry agent id, confirmed the
same way.

## The shape

1. **`campaignClaim`** — a `type: task` leases up to `batch_size` pending items for
   this run.
2. **`type: batch` with `ledger: campaign`** — fans out over the claimed items
   (`items_from: claim`, `concurrency: N`); each per-item task's success/failure is
   written back to the ledger automatically as `campaignComplete`/`campaignFail`.
3. **A `campaign-config` fenced block** after the YAML tells Studio the list
   source, cycle (`once`/`hourly`/`daily`/`weekly`/`monthly`/`continuous`), cron
   `schedule`, `max_attempts`, and optional delivery/chaining.

```yaml
workflow:
  name: "Status-page watch"
  tasks:
    - type: task
      id: claim
      agent: data-table-agent
      operation: campaignClaim
      campaign_id: "<written by Studio at save>"
      batch_size: 50
    - type: batch
      id: work
      items_from: claim
      concurrency: 5
      ledger: campaign
      tasks:
        - type: task
          id: one
          agent: firecrawl-agent
          operation: scrape
          url: "{item.key}"
          formats: [markdown]
```

```campaign-config
list: { inline: ["https://status.example-a.com", "https://status.example-b.com"] }
cycle: continuous
cycle_start: reset
schedule: "0 * * * *"
max_attempts: 3
deliver: [{ channel: slack }]
```

## Keeping it going

A campaign with a `schedule` in its config runs on an ordinary recurring cron job.
One WITHOUT a schedule ends its pipeline with `agent: scheduler, operation:
runAgain, in: "1h"` — a self-scheduling `@once` job that never stacks. Both
mechanisms and full cron/date-token detail: `plungeai-scheduling`.

## Gotchas

- **`upsertRow` is insert-only, not keyed** — it does not match `matchFields`; use
  `chainStep` or explicit `col_<name>` columns for an idempotent per-item write, or
  `updateRows` to change an existing row.
- Never chain (`then`) a dependent *analysis* report onto a data-collection
  campaign — a partial cycle must not trigger it; keep such reports time-triggered.
- The scheduler's zero-progress breaker auto-pauses a campaign after several
  consecutive runs that complete nothing — check `campaignStatus` before assuming
  it needs a manual nudge.
- Every ledger operation is scoped to the caller's own account — there is no
  cross-tenant campaign surface today.

## Related skills

- `plungeai-campaign-agent` — the Studio kind that authors campaigns visually
  (kept id — this skill documents its underlying mechanics, not a replacement UI).
- `plungeai-workflows` — the `batch`/`task`/`harness` types a campaign pipeline is
  built from.
- `plungeai-scheduling` — cron cadence, `@once`, and `runAgain` self-scheduling.
- `plungeai-missions` — when a per-item step needs judgment instead of a fixed call.
- `plungeai-results-traces` — reading a campaign run's execution history.

## Reference

- `references/campaigns.md` — the `campaign-config` field table, every ledger
  operation (`campaignBegin`/`Claim`/`Complete`/`Fail`/`Release`/`Status`/
  `AddItems`/`RetryFailed`/`SetStatus`/`Delete`/task rows/`chainStep`/`counterStep`),
  sizing, delivery channels, and gotchas.