name, a cron timing, and a session_request template:
Timing
Timing field
expressionis standard five-field cron (minute hour day-of-month month day-of-week), evaluated in the IANAtimezone.0 9 * * 1-5fires at 09:00 Paris time every weekday, across daylight-saving changes.- It may not fire more often than once every 5 minutes.
typeis optional:"cron"is the default and only variant.next_run_timeslists the next 5 fires (empty while paused).
The session template
session_request takes the Create session body. It is re-resolved on every fire, so a catalog agent like "h/web-surfer-flash" always runs its current version.
- It must contain at least one initial message.
- It may not set
parent_session_id. max_time_sdefaults to 3600 seconds.
Fire outcomes
Every fire is recorded in the schedule’s run history (kept 90 days):
Fires never queue: a skipped fire is skipped for good, and the schedule fires again at the next cadence point.
Pausing and failures
A fixed number of sessions
Setrepeats to stop after a fixed number of sessions. Each automatic fire that creates a session counts. When sessions_created reaches repeats, the schedule pauses. To run more, raise repeats (or set it to null) and resume. Omit repeats to fire until you pause or delete the schedule.
Consuming the results
Nobody polls a scheduled session, so pair it with a webhook: get a signed event when each session settles, then read its answer with Get session. To inspect in bulk, filter List sessions byschedule_id. Each run record also links to its session.
Constraints
- Up to 20 schedules per organization.
- Deleting a schedule stops future fires. Sessions already created keep running.