plungeai-campaigns

Run a list to completion on PlungeAI: the campaign ledger (claim/complete/fail/retry), the campaign-config (list source, cycle, cadence, retries, delivery), and how a campaign keeps going via cron or self-scheduling runAgain. A campaign is a saved workflow of kind campaign: create it over the One API (POST /v1/workflows with kind: campaign + campaign_config), MCP (plungeai_workflow) or Studio. 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. Ledger status, pause and stop are Studio-session routes (ocean-cli campaigns); authoring UI: plungeai-campaign-agent; for the pipeline steps use plungeai-workflows.

Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)

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 (opens in a new tab)) for REST (https://api.plungeai.com) and MCP (https://mcp.plungeai.com/v1), or build the pipeline in Ocean Studio.
• A campaign is a saved workflow with kind: campaign. REST, MCP and Studio create the same row; the ledger operations below are the engine's own (data-table-agent is an internal agent with no registry card — you do not discover or call it, you write it into the campaign YAML and the platform arms the ledger at save).

Over the One API, MCP and CLI

curl -s -X POST https://api.plungeai.com/v1/workflows \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile yaml watch.yaml '{name: "Status-page watch", kind: "campaign", yaml: $yaml,
       campaign_config: {list: {inline: ["https://status.example-a.com", "https://status.example-b.com"]},
                         cycle: "continuous", schedule: "0 * * * *", max_attempts: 3}}')"

What builders get wrong:

• campaign_config is JSON on REST and MCP (the campaign-config fenced block is the Studio spelling of the same fields): list with exactly one of table, agent, csv, inline; cycle; max_attempts (integer ≥ 1) are required; cycle_start, schedule (5-field cron), batch_size, max_items, pace, then, deliver, local are optional. 422 invalid_params names the field and nothing is created; kind other than campaign with a campaign_config is 422 too. The Studio-only task_types and learn keys are dropped.
• A 201 can still carry warnings: campaign setup did not complete — the workflow is saved without its ledger, Ledger not created: …, or a rejected schedule. Read them; the row exists either way.
• No schedule means no scheduler job. The ids of the ledger and the job are not in the 201: find the job with GET /v1/schedules (named <name> - Campaign). For a campaign you build over the API, set schedule.
• The save is linted (422 invalid_workflow, errors listed): exactly ONE agent: data-table-agent, operation: campaignClaim task and ONE type: batch task with items_from and ledger: campaign; concurrency ≤ 5; no ask_user or platform_action inside the batch (it is unattended); an inner type: harness task lists task_complete in allowed_tools; max_items is required when an inner task can reach data-table-agent.
• DELETE is a teardown, not a cascade: the campaign's jobs go and its ledger header is tombstoned, results stay. The same teardown runs when a PATCH moves kind away from campaign.
• Every route is yours only: another account's campaign id is workflow_not_found, like a missing one.

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>"} (REST: GET /v1/discovery/search?kind=agents&q=…). The ledger agent data-table-agent is the exception: it is internal to the engine, has no discoverable card, and is named only in the claim task of the campaign YAML.

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 tells the platform the list source, cycle (once/hourly/daily/weekly/monthly/continuous), cron schedule, max_attempts, and optional delivery/chaining: the campaign_config JSON on REST and MCP, a campaign-config fenced block after the YAML in Studio.

workflow:
  name: "Status-page watch"
  tasks:
    - type: task
      id: claim
      agent: data-table-agent
      operation: campaignClaim
      campaign_id: "<written 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]

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.

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.

Reference pages