# list\_schedule\_runs

List a live or archived schedule's newest runs, newest first, each with its state and why it was skipped or failed.

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

## Calling it

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

```bash
komrad rpc list-schedule-runs \
  --id '<uuid>'
```

```json
{
  "name": "list_schedule_runs",
  "arguments": {
    "id": "<id>"
  }
}
```

Offered by the komrad MCP server to orchestrator agents.

## Request

### ListScheduleRunsRequest

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/schedule/list-schedule-runs.md#komrad-schedule-v1-ListScheduleRunsRequest-id) | uuid\* | The schedule whose runs to list, by id. |
| [`limit`](https://komrad.dev/latest/api/schedule/list-schedule-runs.md#komrad-schedule-v1-ListScheduleRunsRequest-limit) | int32 between 0 and 200 | How many of the newest runs to return. Zero returns twenty. |

## Response

### ListScheduleRunsResponse

| Field | Type | Description |
| --- | --- | --- |
| [`runs`](https://komrad.dev/latest/api/schedule/list-schedule-runs.md#komrad-schedule-v1-ListScheduleRunsResponse-runs) | [ScheduleRun\[\]](https://komrad.dev/latest/api/schedule/list-schedule-runs.md#komrad-schedule-v1-ScheduleRun) | The schedule's runs on record, newest first. |

## Types

### 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-schedule-runs.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-schedule-runs.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-schedule-runs.md#komrad-schedule-v1-ScheduleRun-state) | [ScheduleRunState](https://komrad.dev/latest/api/schedule/list-schedule-runs.md#komrad-schedule-v1-ScheduleRunState) | The run's state. |
| [`attempt`](https://komrad.dev/latest/api/schedule/list-schedule-runs.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-schedule-runs.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-schedule-runs.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-schedule-runs.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. |

### ScheduleRunState

ScheduleRunState is the state of one schedule run.

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