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

# Schedules

> Run a procedure on a timetable: a cron expression in your time zone, the inputs it needs, and a record of every run with what the agent found.

A schedule runs one of an agent's procedures on a timetable: every weekday at 9:00 in New York, every 15 minutes, on the 1st of the month. Set one up on the agent’s **Schedules** tab in the console, by asking the agent in Coach (its change waits for your OK), or with the API.

Each run is a conversation of its own, with nobody in it:

* The schedule's **inputs** are the conversation's [variables](https://docs.guidinghand.ai/concepts/conversations.md), with `channel` set to `schedule`. They must give every required input of the procedure, since nobody is there to ask.
* A procedure with **steps without AI** runs on its steps straight away, with no lookup and no model. Otherwise the agent's model follows the procedure to its end and says what it did and found.
* Anything the procedure does happens as it would in any live conversation: its browser and desktop tasks, its [escalations](https://docs.guidinghand.ai/concepts/escalations.md) (a hand-off, a failed procedure), and approvals only your team can give. A run waiting on your team shows as `waiting` until it's decided.
* It runs the agent's **published** version, and is charged like any conversation. Its `cost_cents` is what its replies and tasks came to.

## When it runs

`cron` has five fields: minute, hour, day of the month, month and day of the week. Each takes `*`, numbers, ranges (`1-5`), steps (`*/15`) and lists (`1,15`), and months and days by name (`JAN`, `MON`). `@hourly`, `@daily`, `@weekly`, `@monthly` and `@yearly` work too. Times are read in the schedule's `time_zone`, through daylight saving changes: a time the clock skips doesn't run that day, and a time that comes twice runs the first time.

| Cron | Runs |
| - | - |
| `0 9 * * 1-5` | Every weekday at 09:00 |
| `*/15 * * * *` | Every 15 minutes |
| `30 7 * * MON,FRI` | Every Monday and Friday at 07:30 |
| `0 6 1 * *` | On the 1st of every month at 06:00 |

`GET /v1/schedules/preview?cron=…&time_zone=…` says an expression in words and lists its next runs.

## Runs

Every run is recorded, with when it was due, how it ended (`completed`, `failed`, `stopped`), what the agent said last (`result`), its conversation and how many escalations it raised. A slot that didn't run is recorded too:

* `skipped`: the schedule's last run was still going, or your org already had 5 scheduled runs going.
* `missed`: Eager wasn't running when it was due (a restart) and it would have been over an hour late. A run up to an hour late still runs.

**Run now** (`POST …/schedules/{id}/run`) runs it at once, paused or not. Pausing stops its runs until you resume it; a resumed schedule counts its next run from then.

## Who hears

Your org's [webhook](https://docs.guidinghand.ai/guides/webhooks.md) gets `schedule.run_completed` or `schedule.run_failed` (failed, stopped, skipped or missed) with the schedule and the run. Each schedule can also email org members and post in the Slack or Teams channel your linked workspaces take escalations in (`notify`): on every run, only when one fails (the default) or never.

```json theme={null}
{
  "procedure_id": "prc_3s9…",
  "name": "Morning warranty check",
  "cron": "0 9 * * 1-5",
  "time_zone": "America/New_York",
  "inputs": { "region": "EMEA" },
  "notify": { "on": "failure", "emails": ["ops@acme.com"], "chat_apps": true }
}
```

## Limits

An org can have 25 schedules, each running at most every 5 minutes, with up to 5 runs going at once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.