Skip to main content
A scheduled task runs a coworker with no user message. Its body is the instruction the coworker receives when it fires. See Automations for the concept.

list_schedules

Lists a coworker scheduled tasks in full: slug, name, body, cron or runAt, timezone, the connection and model of its own when it has one, enabled state and last run.
string
required
This is how you audit what an existing scheduled task actually does.

upsert_schedule

Creates a scheduled task, or updates it when slug is given.
string
required
string
Omit to create. Pass an existing slug to update.
string
Required when creating. The slug is derived from it.
string
Required when creating. The instruction sent to the coworker when the task fires, written as if you were talking to it.
string
Standard 5-field cron, for example 0 9 * * 1 for every Monday at 9. Required when creating unless you pass runAt.
string
ISO date for a one-off run. The task disables itself after it fires.
string
IANA timezone, for example Europe/Paris. Without it, the cron is read in the timezone of your machine.
string
boolean
string
Run this one on a given AI connection, by its id from list_ai_connections. Goes with model.
string | null
Run this one on a model of its own. Omit it and it runs whatever its coworker runs. Pass null to go back to that.
Two things to know. The slug is derived from the name and is what run_schedule_now and delete_schedule address, so read it back from the response. And an update can change a cron but cannot clear it, nor turn a recurring task into a one-off: delete and recreate for that.

run_schedule_now

Fires a scheduled task immediately, without waiting for its cron.
string
required
string
required
It works on a disabled task, does not enable it, and does not touch its last-run date. That makes it safe for testing an instruction before putting the task live. Returns a runId. Read the outcome with get_run.

delete_schedule

string
required
string
required
boolean
required
Must be true.