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. 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 (opens in a new tab) · View raw SKILL.md (opens in a new tab)

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 (opens in a new tab)), 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.

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.

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.

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 — full action table, cron/date-token reference, heartbeat semantics, retries/history, troubleshooting, and the plungeai_schedule MCP tool contract.

Reference pages