# list\_schedules

List schedules, most recently updated first, each with its latest run.

read-only · idempotent · MCP tool · [Schedule](https://komrad.dev/latest/api/schedule.md)

Archived schedules are left out unless [`archived`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ListSchedulesRequest-archived) is set.

## Calling it

```bash
curl -X POST http://127.0.0.1:8787/komrad.schedule.v1.ScheduleService/ListSchedules \
  -H 'Content-Type: application/json' \
  -d '{}'
```

```bash
komrad rpc list-schedules
```

```json
{
  "name": "list_schedules",
  "arguments": {}
}
```

Offered by the komrad MCP server to orchestrator agents.

## Request

### ListSchedulesRequest

| Field | Type | Description |
| --- | --- | --- |
| [`pagination`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ListSchedulesRequest-pagination) | [Pagination](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-pagination-v1-Pagination) | The page to read. |
| [`archived`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ListSchedulesRequest-archived) | bool | Whether to list only archived schedules instead of live ones. |

## Response

### ListSchedulesResponse

| Field | Type | Description |
| --- | --- | --- |
| [`schedules`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ListSchedulesResponse-schedules) | [Schedule\[\]](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule) | One page of schedules, most recently updated first. |
| [`next_page_token`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ListSchedulesResponse-next_page_token) | string | The cursor for the next page. Unset on the last page. |

## Types

### Pagination

Pagination selects one page of a listing.

| Field | Type | Description |
| --- | --- | --- |
| [`limit`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-pagination-v1-Pagination-limit) | int32 at least 0 | How many records to return. Komrad caps the value, and picks one when unset. |
| [`cursor`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-pagination-v1-Pagination-cursor) | string at most 2048 characters | The `next_page_token` from the previous response. Unset to start from the first page. |

### Schedule

Schedule is a cron expression that creates a task or mails an orchestrator each time it matches.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-id) | uuid\* | The schedule's id. |
| [`name`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-name) | string | The schedule's name. |
| [`cron`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-cron) | string | The schedule's cron expression, in five fields. |
| [`timezone`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-timezone) | string | The timezone the cron expression is read in. Empty uses the machine's timezone. |
| [`enabled`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-enabled) | bool | Whether the schedule is enabled. A disabled schedule keeps its record and never runs. |
| [`prompt`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-prompt) | string | The prompt each launched writer starts with, or the mail sent to the orchestrator. |
| [`workflow_id`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-workflow_id) | uuid\* | The id of the workflow the schedule belongs to. For an orchestrator schedule, the orchestrator's workflow. |
| [`kind`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-kind) | [ScheduleKind](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleKind) | Whether the schedule creates a task or mails an orchestrator. |
| [`orchestrator_agent_id`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-orchestrator_agent_id) | uuid | The id of the orchestrator the schedule mails. Set only on an orchestrator schedule. |
| [`next_run_at`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-next_run_at) | timestamp | When the cron expression next matches. Unset while the schedule is disabled. |
| [`latest_run`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-latest_run) | [ScheduleRun](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRun) | The schedule's newest run. Unset when the schedule has never run or the run's record has expired. |
| [`recent_runs`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-recent_runs) | [ScheduleRun\[\]](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRun) | The schedule's newest runs, newest first. Set only in `Watch` events. |
| [`archived_at`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-Schedule-archived_at) | timestamp | When the schedule was archived. Unset while the schedule is live. |

### ScheduleRun

ScheduleRun is one time a schedule's cron expression matched, with its state.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRun-id) | int64 | The run's id. A higher id is a newer run. |
| [`scheduled_for`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRun-scheduled_for) | timestamp | The time the cron expression matched for this run. |
| [`state`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRun-state) | [ScheduleRunState](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRunState) | The run's state. |
| [`attempt`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRun-attempt) | int32 | The run's current attempt, counting from one once the run has started. |
| [`max_attempts`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRun-max_attempts) | int32 | How many attempts the run has before it is discarded. |
| [`finalized_at`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRun-finalized_at) | timestamp | When the run finished. Unset while the run is waiting or running. |
| [`message`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRun-message) | string | Why the run was skipped, or the error from its last failed attempt. Empty when the run completed. |

### ScheduleKind

ScheduleKind is what a schedule does each time its cron expression matches.

| Value | Description |
| --- | --- |
| [`orchestrator`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleKind-orchestrator) | Mails the prompt to a running orchestrator. |
| [`task`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleKind-task) | Creates a task in the workflow and launches its writer with the prompt. |

### ScheduleRunState

ScheduleRunState is the state of one schedule run.

| Value | Description |
| --- | --- |
| [`available`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRunState-available) | Waiting to start. |
| [`pending`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRunState-pending) | Held back until something releases the run. |
| [`scheduled`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRunState-scheduled) | Waiting for a later time to start. |
| [`running`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRunState-running) | Running now. |
| [`retryable`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRunState-retryable) | Failed an attempt and waiting to try again. |
| [`completed`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRunState-completed) | Launched the run's agent or sent the run's mail. |
| [`cancelled`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRunState-cancelled) | Skipped, with the reason in the run's message. |
| [`discarded`](https://komrad.dev/latest/api/schedule/list-schedules.md#komrad-schedule-v1-ScheduleRunState-discarded) | Out of attempts, with the last error in the run's message. |
