> ## 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.

# Schedules

> Run a session on a recurring cron cadence.

A schedule creates a [session](/computer-use-agents/sessions/overview) on a recurring cadence: a five-field cron expression evaluated in an IANA timezone, paired with a session template that is re-resolved on every fire. Use it for recurring work like a daily scrape or an hourly check.

Manage schedules with the [CRUD API](/computer-use-agents/schedules/create). Each one has a `name`, a `timing`, and a `session_request` template:

<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",
      "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",
      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",
    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>

## Timing

```json Timing field theme={null}
"timing": {
  "type": "cron",
  "expression": "0 9 * * 1-5",
  "timezone": "Europe/Paris"
}
```

The expression is standard five-field cron (`minute hour day-of-month month day-of-week`), evaluated in the given timezone, so `0 9 * * 1-5` fires at 09:00 Paris time every weekday, across daylight-saving changes. An expression may not fire more often than once every 5 minutes. The `type` tag is optional on requests; `"cron"` is the default and only variant today.

The schedule object reports its upcoming fires in `next_run_times` (the next 5, empty while paused).

## The session template

`session_request` takes the same shape as the [Create session](/computer-use-agents/sessions/create) body. It is stored as a template and re-resolved on every fire, so a catalog agent like `"h/web-surfer-flash"` always runs its current version. Two restrictions apply: the template must contain at least one initial message, and it may not set `parent_session_id`. If the template does not set `max_time_s`, scheduled sessions default to 3600 seconds.

## Fire outcomes

Every fire is recorded in the schedule's [run history](/computer-use-agents/schedules/runs), whether or not it created a session:

| Status            | Meaning                                                                      |
| ----------------- | ---------------------------------------------------------------------------- |
| `created`         | A session was created; the run carries its `session_id`.                     |
| `skipped_overlap` | The session from a previous fire was still active, so this fire was skipped. |
| `skipped_quota`   | Your organization was at quota, so this fire was skipped.                    |
| `error`           | Session creation failed; the run carries the `error` detail.                 |

Fires do not queue behind each other: a skipped fire is skipped for good, and the schedule simply fires again at the next cadence point. Run history is retained for 90 days.

## Pausing and failures

[Pause](/computer-use-agents/schedules/pause) stops future fires without deleting the schedule, and [Resume](/computer-use-agents/schedules/resume) recomputes the next fire from now. After 5 consecutive `error` fires, the schedule is paused automatically with an explanatory `pause_note`. A successful fire or a resume resets the counter.

[Trigger](/computer-use-agents/schedules/trigger) fires a schedule once immediately, even while paused, without affecting the regular cadence. Use it to test a template before the first scheduled fire.

## Consuming the results

Nobody is polling a scheduled session, so pair schedules with a [webhook](/computer-use-agents/webhooks/overview): you receive a signed event when each scheduled session reaches a settled state, then fetch its answer with [Get session](/computer-use-agents/sessions/retrieve). For batch inspection, list a schedule's sessions with the `schedule_id` filter on [List sessions](/computer-use-agents/sessions/list); each fire's [run record](/computer-use-agents/schedules/runs) also links to its session.

## Constraints

* An organization can have up to 20 schedules.
* The cron expression may not fire more often than once every 5 minutes.
* Deleting a schedule stops future fires; sessions already created keep running.