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

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# On schedule

> Start an automation on a recurring five-field cron schedule.

`onSchedule` starts an automation at recurring times. Use it for reports,
maintenance, synchronization, and other work that does not depend on an
external provider event.

## Example

```ts automations/weekday-report.automation.ts theme={null}
import { automation, log, onSchedule } from "automate.ax"

export default automation("Weekday report", () => {
  const tick = onSchedule({
    schedule: "30 9 * * 1-5",
    timeZone: "America/Los_Angeles",
  })

  log({ value: tick.scheduledAt })
})
```

This automation runs at 9:30 AM every Monday through Friday in Los Angeles
local time.

## Options

| Property   | Type     | Required | Description                                                                     |
| ---------- | -------- | -------- | ------------------------------------------------------------------------------- |
| `schedule` | `string` | Yes      | Five-field cron expression: minute, hour, day of month, month, and day of week. |
| `timeZone` | `string` | No       | IANA time zone used to evaluate the schedule. Defaults to `UTC`.                |

The schedule has one-minute precision. Six-field expressions with seconds are
not accepted.

## Trigger data

Returns a `Signal<ScheduleEvent>` for each matching occurrence:

```ts theme={null}
interface ScheduleEvent {
  scheduledAt: Date
}
```

`scheduledAt` is the exact scheduled minute represented by the event. Use it
instead of the automation's wall-clock start time when a delayed execution
still needs to identify its intended occurrence.

## Behavior

* Schedule configuration is validated during deployment.
* IANA time zones follow local daylight-saving-time transitions.
* Only the active deployment receives scheduled events.
* Retries for the same schedule and timestamp are deduplicated.