Skip to main content
A schedule runs one of an agent’s procedures on a timetable: every weekday at 9:00 in New York, every 15 minutes, on the 1st of the month. Set one up on the agent’s Schedules tab in the console, by asking the agent in Coach (its change waits for your OK), or with the API. Each run is a conversation of its own, with nobody in it:
  • The schedule’s inputs are the conversation’s variables, with channel set to schedule. They must give every required input of the procedure, since nobody is there to ask.
  • A procedure with steps without AI runs on its steps straight away, with no lookup and no model. Otherwise the agent’s model follows the procedure to its end and says what it did and found.
  • Anything the procedure does happens as it would in any live conversation: its browser and desktop tasks, its escalations (a hand-off, a failed procedure), and approvals only your team can give. A run waiting on your team shows as waiting until it’s decided.
  • It runs the agent’s published version, and is charged like any conversation. Its cost_cents is what its replies and tasks came to.

​
When it runs

cron has five fields: minute, hour, day of the month, month and day of the week. Each takes *, numbers, ranges (1-5), steps (*/15) and lists (1,15), and months and days by name (JAN, MON). @hourly, @daily, @weekly, @monthly and @yearly work too. Times are read in the schedule’s time_zone, through daylight saving changes: a time the clock skips doesn’t run that day, and a time that comes twice runs the first time. GET /v1/schedules/preview?cron=…&time_zone=… says an expression in words and lists its next runs.

​
Runs

Every run is recorded, with when it was due, how it ended (completed, failed, stopped), what the agent said last (result), its conversation and how many escalations it raised. A slot that didn’t run is recorded too:
  • skipped: the schedule’s last run was still going, or your org already had 5 scheduled runs going.
  • missed: Eager wasn’t running when it was due (a restart) and it would have been over an hour late. A run up to an hour late still runs.
Run now (POST …/schedules/{id}/run) runs it at once, paused or not. Pausing stops its runs until you resume it; a resumed schedule counts its next run from then.

​
Who hears

Your org’s webhook gets schedule.run_completed or schedule.run_failed (failed, stopped, skipped or missed) with the schedule and the run. Each schedule can also email org members and post in the Slack or Teams channel your linked workspaces take escalations in (notify): on every run, only when one fails (the default) or never.

​
Limits

An org can have 25 schedules, each running at most every 5 minutes, with up to 5 runs going at once.