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

# Routing Schedule

> A Routing Schedule runs route optimization for a hub automatically at the times you set

## What is a Routing Schedule?

A Routing Schedule runs route optimization for a hub automatically at the times you set, without anyone opening the app. Its attributes consist of IDs, the Configuration Profile it uses, repetition data (daily, weekly, monthly, by date, or a custom interval), the active window of the schedule, an Auto Dispatch flag, and the outcome of the last run.

Every run reads the Configuration Profile named by `configurationId`, which is what supplies the **hub** and the **vehicles**. Neither is sent when you create the schedule, and neither is copied into it — a change to the profile applies to the very next run.

**Related Guide:** [Routing Schedule](https://docsy3.mile.app/pages/route-optimization/schedule/introduction.md)

## Key Features

> [card] [Read routing schedule](https://docsy3.mile.app/api-reference/routing/routing-schedule/read-routing-schedule.md)
>
> GET /routing/schedules

> [card] [Read routing schedule by ID](https://docsy3.mile.app/api-reference/routing/routing-schedule/read-routing-schedule-by-id.md)
>
> GET /routing/schedule/{scheduleId}

> [card] [Create routing schedule](https://docsy3.mile.app/api-reference/routing/routing-schedule/create-routing-schedule.md)
>
> POST /routing/schedule

> [card] [Update routing schedule by ID](https://docsy3.mile.app/api-reference/routing/routing-schedule/update-routing-schedule-by-id.md)
>
> PUT /routing/schedule/{scheduleId}

> [card] [Update partially routing schedule by ID](https://docsy3.mile.app/api-reference/routing/routing-schedule/update-partially-routing-schedule-by-id.md)
>
> PATCH /routing/schedule/{scheduleId}

> [card] [Delete routing schedule by ID](https://docsy3.mile.app/api-reference/routing/routing-schedule/delete-routing-schedule-by-id.md)
>
> DELETE /routing/schedule/{scheduleId}

## Permissions

Each endpoint is guarded by its own data permission. A call made without it answers `403` with the `sys-035` code.

| Endpoint | Permission |
| - | - |
| `GET /routing/schedules` | `view/routing-schedule` |
| `GET /routing/schedule/{scheduleId}` | `view/routing-schedule` |
| `POST /routing/schedule` | `add/routing-schedule` |
| `PUT /routing/schedule/{scheduleId}` | `edit/routing-schedule` |
| `PATCH /routing/schedule/{scheduleId}` | `edit/routing-schedule` |
| `DELETE /routing/schedule/{scheduleId}` | `delete/routing-schedule` |

Schedules are scoped to your organization. A schedule that belongs to another organization is reported as not found rather than returned.

## Repeat Cycle

`periode` decides how the schedule repeats, and it decides the shape of each entry in `schedules`.

| `periode` | Entry shape | Active window |
| - | - | - |
| `daily` | `{ "time": ["08:00", "15:00"] }` | `startTime` and `endTime` required |
| `weekly` | `{ "day": "monday", "time": ["08:00"] }` | `startTime` and `endTime` required |
| `monthly` | `{ "date": "01", "time": ["08:00"] }` | `startTime` and `endTime` required |
| `byDate` | `{ "date": "2026-09-15", "time": ["08:00"] }` | not used — the dates are absolute |
| `custom` | follows the entry shape of `frequency` | `startTime` and `endTime` required, plus `frequency` and `interval` |

`startTime` and `endTime` use the `Y-m-d H:i` format, and times use `H:i`. Schedules are evaluated once a minute against the application timezone, so a run starts within a minute of its scheduled time.

> [!NOTE]
>
> For `monthly`, `date` is the day of the month written as **two digits** — `"01"`, not `"1"`. For `byDate`, `date` is a full `Y-m-d` date.

`timeSchedules` appears in every response. It is the timetable the server derives from `periode` and `schedules`, and it is read-only — send `periode` and `schedules` and let the server rebuild it.

## What a Run Does

1. Collects the hub's active visits — those with a status of `UNASSIGNED` or `ONGOING`. A single run collects at most **1500** visits, oldest first by creation time.
2. Reads vehicles and optimization settings from the Configuration Profile. Vehicles under [maintenance](https://docsy3.mile.app/api-reference/routing/vehicle-maintenance-overview.md) on the day of the run are left out unless they are forced active; when none is left, the run is skipped with the reason `no_vehicle`.
3. Creates a routing result named `{schedule name} - {date time}`, marked `createdFrom: "SCHEDULER"`, so scheduled results are distinguishable from manual ones. It appears in Routing → Result like any other.
4. Dispatches every vehicle on the result when `autoDispatch` is `true`, and stops after step 3 when it is `false`.

The outcome of the last run is reported in `logExecuted`, including the status, the reason it was skipped or failed, the routing result it produced, and the dispatch counts. A schedule that has never run has no `logExecuted`.

## Related Resources

* [Routing](https://docsy3.mile.app/api-reference/routing/overview.md) - Route optimization and routing results
* [Vehicle](https://docsy3.mile.app/api-reference/routing/vehicle-overview.md) - Vehicles used by a run
* [Task Schedule](https://docsy3.mile.app/api-reference/task/task-schedule-overview.md) - The same repetition model, applied to tasks


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