> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# plungeai-scheduling

> Cron-schedule PlungeAI workflows, agent queries, pre-built agent cards, and condition-watching heartbeats via plungeai_schedule, with full run history and retries.


Cron-schedule PlungeAI workflows, agent queries, pre-built agent cards, and condition-watching heartbeats via plungeai_schedule, with full run history and retries. Also one-time runs (`@once` + `run_at`), wake-ups, and webhook/email/outbound-hook triggers, over MCP, REST (`/v1/schedules`, `/v1/triggers`) and the CLI. Use when the user wants something to run daily/hourly/on a cron, once at a clock time, 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`.

[Download zip](https://skills.plungeai.com/plungeai-scheduling.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-scheduling/SKILL.md)

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` or `check_workflow` + `condition_prompt`, ticks and only acts when the
condition is met — of the six `notify_channel` values, telegram/discord/slack/teams/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 unless the job carries an IANA `timezone`), 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`](/skills/plungeai-scheduling/references/scheduling).

## One-time runs, wake-ups, triggers

- **One run at a clock time:** `schedule: "@once"` plus `run_at` — an ISO-8601 time WITH a UTC
  offset (`2026-10-06T09:00:00Z`), in the future. Without it the create is refused (`run_at
  required` on MCP, `400 run_at_required` on REST; a past time is `400 run_at_past`). The job
  fires once and removes itself; its history stays. `ends_at` (ISO-8601) stops a
  recurring job after a date.
- **Wake:** fire a saved workflow or bot once without touching its schedule — a pending wake is
  re-timed, never stacked. `note` becomes the run's input. REST also takes `in` (`"10m"`) to delay
  it; MCP and CLI wake on the scheduler's next tick. A heartbeat has no saved workflow to wake.
- **Triggers** start a schedule's workflow from outside: a `webhook` (an HTTPS URL; schemes
  generic, github, gitlab, standard-webhooks; `prompt_template` with `{dotted.path}` fields;
  `filters`), an `email` address (`bot+<token>`, optional `allowed_from`), and outbound `hooks`
  (signed `run.started | run.finished | run.failed | run.needs_approval` events sent to your
  https URL). Mint, list, revoke; on REST only, webhook and email also rotate (`/{token}/rotate`). A secret is shown once, on mint.

| | MCP `plungeai_schedule` | REST (`ozk_` key) | CLI (`ocean-cli`) |
|---|---|---|---|
| one-time | `create` with `schedule: "@once"`, `run_at`, `ends_at` | `POST /v1/schedules` | `schedules create NAME --type workflow --target <workflow id> --cron @once --at <iso> [--ends-at <iso>]` |
| wake | `wake` (`job_id`, `note`) | `POST /v1/schedules/{id}/wake` | `schedules wake <job_id> --note "…"` |
| webhook | `webhook_mint` / `webhook_list` / `webhook_delete` (`job_id`; delete takes `trigger_id`) | `/v1/triggers/webhook` (+ `/{token}`, `/{token}/rotate`) | `schedules triggers webhook mint <job_id> [--scheme --prompt-template --filters]\|list <job_id>\|delete <job_id> <token> --yes` |
| email | `email_mint` / `email_list` / `email_delete` | `/v1/triggers/email` (same shape) | `schedules triggers email mint <job_id> [--allowed-from]` (+ list, delete) |
| outbound hooks | `hooks_mint` / `hooks_list` / `hooks_delete` | `/v1/triggers/hooks` (+ `/{id}`) | `schedules triggers hooks mint <job_id> --url <https> [--events]` (+ list, delete) |

REST creates only `workflow` and `heartbeat` schedules (wrap an agent in a saved workflow
first); every schedule route also lists runs (`GET /v1/schedules/{id}/runs`), pauses, resumes
and runs now (`{run_id, execution_id}`; `execution_id` is what `plungeai-results-traces` takes). Lists take `limit` 1–100
(default 20) and `offset`; `GET /v1/schedules` filters by `status`, `job_type` and `workflow_id`. A bot schedules
itself with its own `schedule` tool (`plungeai-bot-agent`). Route and field detail: `plungeai-api-setup` →
`references/bots-and-door.md`; this skill's [`references/scheduling.md`](/skills/plungeai-scheduling/references/scheduling).

## 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 at `run_at`, 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`](/skills/plungeai-scheduling/references/scheduling) — full action table, cron/date-token reference,
  heartbeat semantics, retries/history, troubleshooting, and the
  `plungeai_schedule` MCP tool contract.

## Reference pages

<CardGroup cols={2}>
<Card title="Scheduling — cron jobs for workflows, agents, and missions" icon="file-text" href="/skills/plungeai-scheduling/references/scheduling">
The scheduler runs platform work unattended on cron expressions: a saved workflow every morning, an agent query hourly, a pre-built agent card nightly.
</Card>
</CardGroup>