name, a timing, and a session_request template:
Timing
Timing field
minute hour day-of-month month day-of-week), evaluated in the given timezone, so 0 9 * * 1-5 fires at 09:00 Paris time every weekday, across daylight-saving changes. An expression may not fire more often than once every 5 minutes. The type tag is optional on requests; "cron" is the default and only variant today.
The schedule object reports its upcoming fires in next_run_times (the next 5, empty while paused).
The session template
session_request takes the same shape as the Create session body. It is stored as a template and re-resolved on every fire, so a catalog agent like "h/web-surfer-flash" always runs its current version. Two restrictions apply: the template must contain at least one initial message, and it may not set parent_session_id. If the template does not set max_time_s, scheduled sessions default to 3600 seconds.
Fire outcomes
Every fire is recorded in the schedule’s run history, whether or not it created a session:
Fires do not queue behind each other: a skipped fire is skipped for good, and the schedule simply fires again at the next cadence point. Run history is retained for 90 days.
Pausing and failures
Pause stops future fires without deleting the schedule, and Resume recomputes the next fire from now. After 5 consecutiveerror fires, the schedule is paused automatically with an explanatory pause_note. A successful fire or a resume resets the counter.
Trigger fires a schedule once immediately, even while paused, without affecting the regular cadence. Use it to test a template before the first scheduled fire.
Consuming the results
Nobody is polling a scheduled session, so pair schedules with a webhook: you receive a signed event when each scheduled session reaches a settled state, then fetch its answer with Get session. For batch inspection, list a schedule’s sessions with theschedule_id filter on List sessions; each fire’s run record also links to its session.
Constraints
- An organization can have up to 20 schedules.
- Deleting a schedule stops future fires; sessions already created keep running.