plungeai-campaigns

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.

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)) 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.

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]

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.

Reference pages