---
title: "List runs"
method: GET
path: "/api/v1/runs"
tags: ["Runs"]
---

# List runs

`GET /api/v1/runs`

List workflow and agent runs with cursor pagination.

## Query parameters

- `type` string
- `source` string
- `status` string
- `trigger` string
- `triggeredBy` string
- `sourceRef` string
- `batchId` string
- `exampleId` string
- `exampleIdContains` string
- `from` string
- `to` string
- `createdAfter` string
- `createdBefore` string
- `completedAfter` string
- `completedBefore` string
- `cursor` string
- `offset` integer
- `limit` integer
- `ids` string
- `experiments` string
- `sort` string
- `order` string
- `reviewStatus` string
- `reviewVerdict` string
- `hasReview` string
- `noReview` string
- `hasCorrections` string
- `reviewNoteContains` string
- `reviewCreatedAfter` string
- `reviewCreatedBefore` string
- `reviewUpdatedAfter` string
- `reviewUpdatedBefore` string
- `reviewClosedAfter` string
- `reviewClosedBefore` string
- `sinceLastClosed` string
- `sampleRate` string — Keep runs whose `sampleRank` is below this threshold (0–1). Pages may return fewer than `limit` rows when filtered.

## Response `200`

Runs page

- RunsListResponse
  - `runs` RunListItem[], required
    - `id` string, required
    - `type` 'workflow' | 'agent', required
    - `finished` boolean, required — True when the run has reached a terminal status.
    - `sampleRank` number, required — Deterministic pseudo-random rank in [0, 1) for this run within the tenant. Use with a sample rate threshold to review a stable subset.
    - `timing` RunTiming, required
      - `createdAt` string, required
      - `startedAt` string, nullable, required
      - `completedAt` string, nullable, required
      - `durationMs` number, nullable, required
      - `cancelRequestedAt` string, nullable, required — When the user requested cancel; status may still be `running` until the worker stops.
    - `source` RunSource, required
      - `id` string, required — Owning workflow id or agent id.
      - `name` string, nullable, required
      - `version` string, nullable, required — Workflow version label (workflow runs only).
      - `versionId` string, nullable — Captured workflow version id (workflow runs only).
      - `slug` string, nullable — Agent slug (agent runs only).
      - `model` string, nullable — LLM model used (agent runs only).
      - `git` RunSourceGit
        - `requestedRef` string, nullable, required
        - `resolvedRef` string, nullable, required
        - `resolvedTag` string, nullable, required
        - `commitSha` string, nullable, required
      - `implementationAvailable` boolean — Whether the live workflow/agent implementation still exists (`GET /api/v1/runs/:id` detail only).
      - `automationFound` boolean — Whether the owning automation registry row still exists (`GET /api/v1/runs/:id` detail only).
      - `currentVersion` string, nullable — Current released workflow version label when the source is live (`GET /api/v1/runs/:id` detail only).
    - `trigger` RunTrigger, required
      - `type` string, nullable, required
      - `by` object, nullable, required
        - `id` string, required
        - `name` string, nullable, required
        - `email` string, required
      - `email` unknown
    - `eval` RunEval
      - `example` string, nullable, required — Eval example label (agent example name or workflow example id).
      - `exampleId` string, nullable — Workflow eval example folder id (workflow runs only).
      - `score` number, nullable, required
      - `passed` boolean, nullable, required
    - `error` string, nullable
    - `execution` RunExecutionMeta, required
      - `status` 'created' | 'pending' | 'running' | 'waiting' | 'finalizing' | 'completed' | 'failed' | 'cancelled' | 'rejected', required
      - `schemaValid` boolean, nullable, required — Whether the completed output matched the workflow or agent output schema.
      - `batchId` string, nullable, required — Experiment batch id when the run is part of a batch.
      - `retry` RunExecutionRetry, required
        - `number` number, required — Retry attempt index (0 = original run).
        - `previousRunId` string, nullable, required — Run id of the prior attempt in the retry chain.
        - `nextRun` object, nullable, required — Retry run spawned from this run, if any.
          - `id` string, required
          - `status` string, required
      - `review` RunReviewSummary
        - `verdict` 'correct' | 'incorrect', nullable, required
        - `status` 'open' | 'closed' | 'wont_fix', required
        - `hasNote` boolean, required — True when review notes were left.
        - `correctionCount` integer, required — Number of field/file corrections.
  - `nextCursor` string, nullable, required

## Other responses

- `400` — Validation error. Request shape did not match the spec.
- `401` — Missing or invalid API key
- `403` — API key lacks required scope
- `404` — Resource not found
- `413` — Payload too large. Upload exceeded the per-request size cap.
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.dev/eigenpal/apis/eigenpal-api.md) · [All operations](https://skmtc.dev/eigenpal/apis/eigenpal-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/eigenpal/eigenpal-api/revisions/dddcddf1975c/schema)