Create a schedule

Create a cron schedule that starts a session on each fire.

POST /api/v2/schedules

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])

201

{
  "id": "9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f",
  "name": "morning-market-scan",
  "description": "Weekday scan of new Paris listings",
  "timing": {"type": "cron", "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"}
    ],
    "max_time_s": 3600
  },
  "paused": false,
  "pause_note": null,
  "repeats": null,
  "sessions_created": 0,
  "next_run_times": [
    "2026-07-06T07:00:00Z",
    "2026-07-07T07:00:00Z",
    "2026-07-08T07:00:00Z",
    "2026-07-09T07:00:00Z",
    "2026-07-10T07:00:00Z"
  ],
  "last_run_at": null,
  "created_at": "2026-07-04T12:00:00Z",
  "updated_at": "2026-07-04T12:00:00Z"
}

Behavior

The session_request template is validated and resolved at creation time (the agent must exist), then re-resolved on every fire.

Request body

name · string · required

Display name for the schedule, 1 to 255 characters.

timing · object · required

When the schedule fires. The expression may not fire more often than once every 5 minutes.

expression · string · required

Five-field cron expression, for example "0 9 * * 1-5".

timezone · string · required

IANA timezone the expression is evaluated in, for example "Europe/Paris".

type · string

"cron", the default and only variant.

session_request · object · required

Template used to create each scheduled session, in the same shape as the Create session body. Must contain at least one initial message, may not set parent_session_id, and may not attach files. Defaults to max_time_s: 3600 when the template does not set it.

description · string

Description, up to 255 characters.

repeats · integer

How many sessions to create before the schedule becomes inactive. Each automatic fire that creates a session counts toward it, but skipped fires, errors, and manual triggers do not. When the count is reached, the schedule is paused and pause_note explains that it became inactive. Omit it to keep firing until you pause or delete the schedule. Must be at least 1.

Response

201 with the created schedule object.

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])

201

{
  "id": "9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f",
  "name": "morning-market-scan",
  "description": "Weekday scan of new Paris listings",
  "timing": {"type": "cron", "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"}
    ],
    "max_time_s": 3600
  },
  "paused": false,
  "pause_note": null,
  "repeats": null,
  "sessions_created": 0,
  "next_run_times": [
    "2026-07-06T07:00:00Z",
    "2026-07-07T07:00:00Z",
    "2026-07-08T07:00:00Z",
    "2026-07-09T07:00:00Z",
    "2026-07-10T07:00:00Z"
  ],
  "last_run_at": null,
  "created_at": "2026-07-04T12:00:00Z",
  "updated_at": "2026-07-04T12:00:00Z"
}

Errors

Status	Cause
400	Organization schedule limit reached (20), or the expression fires more often than once every 5 minutes.
404	The agent in session_request is not found, or not in your organization.
422	Body failed validation: invalid cron expression, unknown timezone, template without messages, template setting parent_session_id, or template attaching files.