---
name: plungeai-scheduling
description: "Cron-schedule PlungeAI workflows, agent queries, pre-built agent cards, and condition-watching heartbeats via plungeai_schedule, with full run history and retries. Use when the user wants something to run daily/hourly/on a cron, a recurring report, a standing watchdog, or asks about job status, retries, or why a scheduled run didn't fire. For the workflow or mission being scheduled use `plungeai-workflows` / `plungeai-missions`; for a list-to-completion campaign's own cadence use `plungeai-campaigns`."
---

# PlungeAI Scheduling — cron jobs for workflows, agents, and missions

The scheduler runs platform work unattended on cron expressions: a saved workflow
every morning, an agent query hourly, a pre-built agent card nightly, or a
condition-watching heartbeat. Every job has first-class run history — nothing here
is fire-and-forget.

## Prerequisites

- A self-service `ozk_` API key from **Dashboard → One API → Keys**
  (https://dashboard.plungeai.com), or an MCP client connected to
  `https://mcp.plungeai.com/v1`.
- The thing being scheduled must already exist and be discoverable:
  `plungeai_list_workflows` for a saved workflow, `plungeai_list_agents {search:
  "…"}` for an agent/check_agent id — never guess an id, it is fence-checked at
  create time.

## Creating a job — `plungeai_schedule`

Action-routed, one tool:

```
plungeai_schedule {action: "create", name: "Daily market brief",
  job_type: "workflow",            # agent | query | workflow | heartbeat
  target: "<workflow id>", schedule: "0 7 * * *"}                # 07:00 UTC daily

plungeai_schedule {action: "list"}
plungeai_schedule {action: "run_now", job_id: "…"}   # always do this right after create
plungeai_schedule {action: "runs", job_id: "…"}      # Execution ID column → plungeai_get_result
plungeai_schedule {action: "stats"}
```

Four `create` shapes — workflow (`target` = a workflow id you own), agent (`target`
= an agent id + `parameters: {prompt}`), query (`target` = `{agent, query}` JSON),
and heartbeat (`check_agent` + `condition_prompt`, ticks and only acts when the
condition is met — of the five `notify_channel` values, telegram/discord/slack/email
all deliver through the normal per-channel adapters; whatsapp is a known gap, prefer
`trigger_workflow` or another channel for it). `mission_ref` on create
schedules a pre-built agent card directly, resolved live at fire time.

Standard 5-field cron, UTC, 1-minute minimum granularity, ±5s accuracy. Use the
rolling date tokens (`{yesterday}`, `{week_start}`, `{last_week_end}`, …) instead of
baking concrete dates into scheduled YAML — full table in
`references/scheduling.md`.

## Verify every job you create

`run_now` fires immediately and reports the REAL outcome plus a resolvable
execution id — always call it right after `create` to prove the job works
end-to-end, rather than waiting for the first natural fire.

## Gotchas

- **Workflow jobs run by reference** — edit the workflow in Studio and the next
  scheduled run uses the latest saved version automatically; there is no "update
  the schedule to change the logic".
- **Delete is soft** — history stays readable, but a deleted job refuses
  run_now/update/pause/resume; there is no undelete.
- Failed runs auto-retry (3 attempts, 5 minutes apart) and **re-fire the FULL job**
  — schedule only idempotent work, or make the workflow itself idempotent.
- A scheduler *run id* (`exec_...`, underscore) is not resolvable by
  `plungeai_get_workflow_status` / `plungeai_get_result` directly — go through
  `action: "runs"` and take its Execution ID column first.
- Scheduled user workflows keep the full per-user memory lifecycle (recall + write)
  — only system jobs and heartbeat checks are memory-free.
- `@once` fires once then soft-deletes; `runAgain` (a workflow's own last step)
  self-schedules the next `@once` run without any cron expression at all — the
  mechanism behind a campaign that "just keeps going."

## Related skills

- `plungeai-workflows` — author the workflow a job runs.
- `plungeai-missions` — author the mission a `mission_ref` job runs.
- `plungeai-campaigns` — a list-to-completion ledger driven by cron or `runAgain`.
- `plungeai-memory` — the recall/write lifecycle of a scheduled run.
- `plungeai-results-traces` — read a job run's status, output, and trace once you
  have its Execution ID.

## Reference

- `references/scheduling.md` — full action table, cron/date-token reference,
  heartbeat semantics, retries/history, troubleshooting, and the
  `plungeai_schedule` MCP tool contract.