Schedules

Run a session on a cron.

Create a schedule

Each schedule has a name, a cron timing, and a session_request template for the session it creates.

Python

from hai_agents import Client

client = Client()

schedule = client.schedules.create_schedule(
    name="morning-market-scan",
    description="Weekday scan of new Paris listings",
    timing={"expression": "0 9 * * 1-5", "timezone": "Europe/Paris"},
    session_request={
        "agent": "h/web-surfer-flash",
        "messages": [
            {"type": "user_message", "message": "Scan new apartment listings in Paris 11e and summarize the top five"}
        ],
    },
)
print(schedule.id, schedule.next_run_times[0])

Each organization has a capped number of schedules, and deleting one stops future fires without stopping sessions already created.

How fires work

Timing

• 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.
• next_run_times lists the next 5 fires (empty while paused).

The session template

session_request takes the Create a session body. It is re-resolved on every fire, so a catalog agent like "h/web-surfer-flash" always runs its current version. Create a schedule lists its rules.

Skipped fires

Every fire, skipped or not, is recorded in the schedule’s run history. A fire is skipped when the previous session is still active (skipped_overlap) or the organization is at quota (skipped_quota). Fires never queue: a skipped fire is skipped for good, and the schedule fires again at the next cadence point.

Repeats

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.

Control a schedule

Action	Effect
Pause	Stops future fires, keeps the schedule.
Resume	Recomputes the next fire from now and resets the error counter.
Trigger	Fires once now, even while paused, without changing the cadence. Use it to test a template.
5 consecutive error fires	Auto-pause with an explanatory pause_note. A successful fire resets the counter.

Nobody polls a scheduled session, so pair it with a webhook: get a signed event when each session settles, then read its answer with Retrieve a session. To inspect in bulk, filter List sessions by schedule_id. Each run record also links to its session.