Skip to main content
A schedule creates a session on a recurring cadence, such as a daily scrape or an hourly check. Each one has a name, a cron timing, and a session_request template:

Timing

Timing field
  • expression is standard five-field cron (minute hour day-of-month month day-of-week), evaluated in the IANA timezone. 0 9 * * 1-5 fires at 09:00 Paris time every weekday, across daylight-saving changes.
  • It may not fire more often than once every 5 minutes.
  • type is optional: "cron" is the default and only variant.
  • next_run_times lists 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_s defaults 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

Set repeats 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 by schedule_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.
Related: Webhooks, Plans and limits