Scheduling

Creating a schedule

Open Workflows › Schedules and press New schedule.

A schedule Synapse AI, an agent or an MCP client creates starts paused, so nothing runs before you have read what each run starts with. It shows you that message and when the first run would be, and asks whether to turn it on; your yes turns it on. You can also turn it on from its row — see Turning a schedule on, and pausing it.

The screens, step by step: Schedules and channels, in the Guides.

Fields

On SynapseOrch Cloud the form reads Name, What it runs (Workflow or Agent), Message, Post the result to, How often — its Kind is Every… or Cron expression — If a run is missed (Skip it or Run it late) and Enabled.

The target must exist and be one of yours: an agent or workflow that is not there, or one of Synapse AI's own, is refused with a 404 — No such agent: agent_123. A schedule can always be switched off; switching it back on checks its timing again.

Turning a schedule on, and pausing it

Each row in Workflows › Schedules has an On / Paused switch in its status column, and Turn on or Pause in its ⋮ menu.

• Pausing is one click. A paused schedule starts no runs until it is turned on again; nothing else about it changes.
• Turning on asks first — Turn on Weekly digest? It runs on its own from now on, until it is paused. — with the message each run starts with and when the first run is: an interval's time, or a cron's times in words, on the schedule's own clock. Cancel is the default.

A schedule turned on after the time its next run was due does not run that missed time: its next run is worked out from when it is turned on.

On SynapseOrch Cloud, turning a schedule on makes you its owner — It will run as you, with your signed-in sites — so its runs use your site sessions. Pausing it does not change who owns it.

Over MCP, turn_on_schedule turns a schedule on, and is marked so a client such as Claude Code asks you first; pause_schedule pauses one without asking.

Interval schedules

Run every N minutes, hours, or days — Run every in the form.

The number is a whole number from 1 to 10,000; anything else is refused with a 422 — An interval must be a whole number from 1 to 10,000.

Examples:

• Every 30 minutes: interval_value: 30, interval_unit: minutes
• Every 6 hours: interval_value: 6, interval_unit: hours
• Every day: interval_value: 1, interval_unit: days

The first run is one interval after the schedule is created. After that, the next run is counted from when the previous run started.

Cron schedules

Use standard 5-field cron syntax for precise timing. In the form, pick a Quick preset — every day, every weekday, every Monday, Saturday or Sunday, or the 1st of the month — and an At hour, on your own clock (At hour (Kolkata time)), or choose Custom expression and type your own. A schedule made in the form runs on your browser's time zone, and the form says the cron back in words on that clock.

Examples:

A cron runs on the schedule's own clock: the time zone it names, else UTC. 0 9 * * 1 with Asia/Kolkata runs at 9 AM in India every Monday (03:30 UTC); with no time zone, at 09:00 UTC. It keeps its wall-clock time when the clocks change: a time that does not exist that day runs at the first minute that does, and a time that happens twice runs once. A time zone must be a place's: 'EST' is not a place's timezone: write the place, like America/New_York, or UTC. An expression that cannot be read is refused with a 422 that says why — That is not a valid cron expression: …

The scheduler checks for due schedules every 30 seconds, so a run can start up to half a minute after its time.

What happens when a schedule fires

1. The next run time is moved forward first, so the schedule can't fire twice
2. The prompt is sent to the target:
   • Agent — any @[path] vault mentions in the prompt are read in, and the agent runs its full reasoning loop. If the agent's model call fails, the schedule run fails. An Orchestrator agent runs its workflow instead, and the schedule run fails if the workflow does
   • Workflow — the prompt becomes the run's user_input
3. The run is logged, and the schedule's last run time is updated. A run that stops on a Human step, or on a tool call waiting for approval, is logged as paused rather than completed

Every run of a schedule uses the same session, schedule_<id>. An agent therefore sees the conversation from its earlier scheduled runs — useful for "compare with last time", but worth knowing if you expect each run to start fresh. A memory-enabled agent's scheduled run leaves a session trace, so the agent can find it later.

When a scheduled agent needs approval. A call its tool policy asks about stops the run and asks in the bell — Daily digest needs approval, with Approve and Refuse. The schedule's conversation in History offers the same question, as Allow once and Refuse. The answer carries the same run on: its log reopens with a RESUMED line saying what the person decided, and a Daily digest completed notice follows when it finishes. Nobody answering within 24 hours expires the call unrun — expired — not run — and the schedule firing again replaces a question still waiting.

On SynapseOrch Cloud, owners and admins also get the question by email, and there is no schedule log to reopen: the answer carries the agent's turn on in its conversation. Approve spends credits as a chat message does, so with none left, or a payment past due, it is refused. See Notifications and email.

Messaging. When the target is an agent assigned to a messaging channel, a successful run's result is posted to that agent's first enabled channel that has a chat to post to, prefixed [Schedule: <name>] Run completed. Workflow schedules, failed runs and paused runs post nothing.

Manual trigger

To run a schedule immediately, without waiting for the next scheduled time:

• In the UI: click the play icon (Run now) on the schedule's row

• From the command line: synapse schedules trigger <schedule_id> (see the CLI)

• Through the API, with an API key:

  curl -X POST http://localhost:3000/api/v1/schedules/{schedule_id}/run \
    -H "Authorization: Bearer YOUR_API_KEY"

A manual run is a test of the schedule. It runs even when the schedule is disabled, and it leaves the next and last run times as they were. The request answers at once with the run's id — {"status": "triggered", "schedule_id": "…", "run_id": "…"} — and returns 404 for an unknown schedule.

The same API lists, creates, reads, changes and deletes schedules: GET and POST /api/v1/schedules, and GET, PATCH and DELETE /api/v1/schedules/{schedule_id}. A PATCH changes only the fields it sends — {"enabled": false} pauses a schedule, {"enabled": true} resumes it.

Missed runs

If SynapseOrch was stopped when a run was due, what happens on restart depends on the schedule type:

The missed-run choice is shown only for cron schedules; interval schedules ignore it.

Example: Daily sales report

{
  "name": "Daily Sales Report",
  "description": "Run the sales report every weekday morning",
  "target_type": "orchestration",
  "target_id": "orch-sales-report",
  "prompt": "Generate the sales report for yesterday",
  "schedule_type": "cron",
  "cron_expression": "0 8 * * 1-5",
  "enabled": true,
  "missed_run_policy": "skip"
}

Example: Hourly health check

{
  "name": "Hourly Health Check",
  "target_type": "agent",
  "target_id": "agent-monitor",
  "prompt": "Check all services and report any anomalies",
  "schedule_type": "interval",
  "interval_value": 1,
  "interval_unit": "hours",
  "enabled": true
}