list_schedule_runs

List a schedule's most recent firings, newest first, each with the occurrence it stands for, its state, its attempt count, and why it was skipped or how it failed.

Scheduleread-onlyidempotentMCP tool

A completed run launched its agent, a cancelled one was skipped on purpose, a discarded one ran out of attempts, and a retryable one is still being tried. Firings are kept for 90 days. Returns not_found if no schedule has that id.

Calling it#

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

komrad rpc list-schedule-runs \
  --id <string>

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

Offered by the komrad MCP server to orchestrator agents.

Request#

ListScheduleRunsRequest#

Field Type Description

Field	Type	Description
`id`	string	Which schedule's firings to read. required
`limit`	int32	How many of the newest firings to return, twenty when unset. between 0 and 200

id

string

Which schedule's firings to read.

required

limit

int32

How many of the newest firings to return, twenty when unset.

between 0 and 200

Response#

ListScheduleRunsResponse#

Field	Type	Description
`runs`	list of ScheduleRun	The firings on record, newest first.

Types#

ScheduleRun#

ScheduleRun is one firing of a schedule, as the job that carried it out stands.

Field	Type	Description
`id`	int64	The job's own id, which orders firings newest first.
`scheduledFor`	timestamp	Which occurrence of the cron expression this firing stands for.
`state`	ScheduleRunState	Where the firing stands.
`attempt`	int32	Which try this is, starting at one once it has been worked.
`maxAttempts`	int32	How many tries it is given before it is discarded.
`finalizedAt`	timestamp	When it finished, unset while it is still waiting or working.
`message`	string	Why it was skipped or what its last failed attempt said, blank once it has launched.

ScheduleRunState#

ScheduleRunState is where River holds a firing's job.

Value	Description
`SCHEDULE_RUN_STATE_AVAILABLE`	Waiting for a worker to pick it up.
`SCHEDULE_RUN_STATE_PENDING`	Held back from running until something releases it.
`SCHEDULE_RUN_STATE_SCHEDULED`	Queued to become available at a later time.
`SCHEDULE_RUN_STATE_RUNNING`	Being worked right now.
`SCHEDULE_RUN_STATE_RETRYABLE`	Failed an attempt and waiting to try again.
`SCHEDULE_RUN_STATE_COMPLETED`	Launched its agent.
`SCHEDULE_RUN_STATE_CANCELLED`	Skipped on purpose, with the reason in its message.
`SCHEDULE_RUN_STATE_DISCARDED`	Ran out of attempts, with the last error in its message.