> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a schedule

> Register a cron schedule that starts a session on each fire.

Registers a [schedule](/computer-use-agents/schedules/overview) for your organization. The `session_request` template is validated and resolved at creation time (the agent must exist), then re-resolved on every fire.

**Returns** `201` with the created [schedule object](/computer-use-agents/schedules/retrieve).

***

## Request body

<ParamField body="name" type="string" required>
  Display name for the schedule (max 255 characters).
</ParamField>

<ParamField body="timing" type="object" required>
  When the schedule fires:

  * `expression` (string): Five-field cron expression, e.g. `"0 9 * * 1-5"`.
  * `timezone` (string): IANA timezone the expression is evaluated in, e.g. `"Europe/Paris"`.
  * `type` (string, optional): `"cron"`, the default and only variant today.

  The expression may not fire more often than once every 5 minutes.
</ParamField>

<ParamField body="session_request" type="object" required>
  Template used to create each scheduled session, in the same shape as the [Create session](/computer-use-agents/sessions/create) body. Must contain at least one initial message and may not set `parent_session_id`. Defaults to `max_time_s: 3600` when the template does not set it.
</ParamField>

<ParamField body="description" type="string">
  Optional description (max 255 characters).
</ParamField>

***

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://agp.eu.hcompany.ai/api/v2/schedules \
    -H "Authorization: Bearer $HAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "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"}
        ]
      }
    }'
  ```

  ```python Python theme={null}
  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])
  ```

  ```typescript TypeScript theme={null}
  import { HaiAgentsClient } from "hai-agents";

  const client = new HaiAgentsClient();

  const schedule = await client.schedules.createSchedule({
    name: "morning-market-scan",
    description: "Weekday scan of new Paris listings",
    timing: { expression: "0 9 * * 1-5", timezone: "Europe/Paris" },
    sessionRequest: {
      agent: "h/web-surfer-flash",
      messages: [
        { type: "user_message", message: "Scan new apartment listings in Paris 11e and summarize the top five" },
      ],
    },
  });
  console.log(schedule.id, schedule.nextRunTimes[0]);
  ```
</CodeGroup>

```json Response theme={null}
{
  "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,
  "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 referenced by `session_request` doesn't exist or isn't visible to you.                                                       |
| `422`  | Body failed validation: invalid cron expression, unknown timezone, template without messages, or template setting `parent_session_id`. |