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

# Scheduling

> Run missions once or on a cron schedule

Schedules are derived from mission fields and exposed as `ScheduleEntry` runtime records. The scheduler evaluates due entries no more often than every 30 seconds by default.

## Create a schedule

```typescript theme={null}
await client.createSchedule({
  missionId: mission.id,
  expression: "0 9 * * 1-5",
  recurring: true,
  endDate: "2026-12-31T00:00:00Z"
});
```

`POST /v1/schedules` accepts:

| Field        | Type    | Description                                                           |
| ------------ | ------- | --------------------------------------------------------------------- |
| `missionId`  | string  | Existing mission ID                                                   |
| `expression` | string  | Five-field cron or future ISO timestamp                               |
| `recurring`  | boolean | Sets mission status to `recurring`; defaults to false and `scheduled` |
| `endDate`    | string  | Optional ISO timestamp after which execution stops                    |

A one-shot schedule disables its entry after the trigger. If mission execution fails, the mission returns to `scheduled` and can be registered for automatic retry. After success it remains completed. A recurring mission returns to `recurring` after either success or failure and computes its next cron occurrence.

When `endDate` is reached, the entry is disabled and the mission transitions to `completed`.

## Cron syntax

Polpo accepts exactly five fields: minute, hour, day of month, month, and day of week. It supports numbers, comma-separated lists, ranges, `*`, and steps such as `*/10`. Day of week accepts 0-7, with both 0 and 7 meaning Sunday.

```txt theme={null}
0 9 * * 1-5     weekdays at 09:00
*/30 * * * *    every 30 minutes
0 */6 * * *     every 6 hours
30 14 1 * *     the first day of each month at 14:30
```

Aliases such as `@daily`, a seconds field, and `L`, `W`, or `#` modifiers are not supported.

There is no timezone field on a schedule. Cron evaluation uses the server process timezone. Author Cloud schedules as UTC; self-hosted operators should set and document the server timezone explicitly. An agent identity's `timezone` does not affect scheduling.

## Manage schedules

| Method   | Path                        | Description                                               |
| -------- | --------------------------- | --------------------------------------------------------- |
| `GET`    | `/v1/schedules`             | List runtime schedule entries                             |
| `POST`   | `/v1/schedules`             | Create a schedule                                         |
| `PATCH`  | `/v1/schedules/{missionId}` | Change expression, recurrence, enabled state, or end date |
| `DELETE` | `/v1/schedules/{missionId}` | Remove the schedule and reset the mission to `draft`      |

`PATCH enabled: false` disables the in-memory entry without deleting the mission's expression. Deleting clears the schedule field.

Local schedule files are stored in `.polpo/schedules/*.json` and use the same `CreateScheduleRequest` shape. `polpo deploy` sends each file to `/v1/schedules`.

<Warning>
  Project configuration does not expose an `enableScheduler` setting. Availability is a server runtime concern; do not add `settings.enableScheduler` to `polpo.json`.
</Warning>