---
title: "Get a run"
method: GET
path: "/api/v1/runs/{id}"
tags: ["Runs"]
---

# Get a run

`GET /api/v1/runs/{id}`

Fetch one run by id. By default this returns core metadata plus terminal output/error fields. Pass `?expand=input,usage,execution,debug` to include detailed sub-objects; `expand=execution` is also where embedded review and expected artifacts appear.

## Path parameters

- `id` string, required — Run id

## Query parameters

- `expand` string — Optional sections: `input`, `usage`, `execution`, `debug`. Terminal runs always include top-level output, files, and error.

## Response `200`

Run detail. Expanded sections appear only when requested.

- Run
  - `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
  - `output` object, nullable — Completed runs only.
  - `files` RunArtifact[] — Completed runs only. Download with GET /api/v1/runs/:id/artifacts/:path.
    - `name` string, required
    - `role` string, required — `input`, `output`, `debug`, `report`, or another stable artifact role.
    - `path` string, required — Canonical artifact path for GET /api/v1/runs/:id/artifacts/:path.
    - `stepName` string — Workflow step that produced the file, when known.
    - `contentType` string, nullable
    - `size` integer, nullable
  - `error` string, nullable
  - `input` RunInput
    - `args` unknown, required
    - `files` RunFile[] — Uploaded input files (agent runs only).
      - `name` string, required
    - `metadata` unknown
  - `usage` RunUsage
    - `tokens` object, required
      - `input` number, nullable, required
      - `output` number, nullable, required
      - `cacheRead` number, nullable, required
      - `cacheWrite` number, nullable, required
    - `creditsCharged` number, nullable, required
    - `durationMs` number, nullable, required
    - `llmCallCount` number — LLM call count (workflow runs only).
    - `ocrPagesProcessed` number — OCR pages processed (workflow runs only).
    - `agentTurns` number, nullable — Agent conversation turns (agent runs only).
  - `execution` union, required — Slim execution metadata always present. Pass `expand=execution` to replace with full RunExecution (WorkflowRunExecution or AgentRunExecution depending on run type).
    - RunExecutionMeta
      - `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.
    - union
      - WorkflowRunExecution
        - `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` RunReview
          - `id` string, required
          - `verdict` 'correct' | 'incorrect', nullable, required
          - `status` 'open' | 'closed' | 'wont_fix', required
          - `note` string, required
          - `correctedOutput` unknown
          - `reviewedBy` string, nullable, required — User id of the last reviewer. Read-only; set from the authenticated user or API key creator.
          - `reviewedByEmail` string, nullable, required — Email of the last reviewer. Read-only; set from the authenticated user or API key creator.
          - `reviewedAt` string, required
          - `closedBy` string, nullable, required — User id recorded when the review was closed. Read-only; set when status becomes closed or wont_fix.
          - `closedByEmail` string, nullable, required — Email recorded when the review was closed. Read-only; set when status becomes closed or wont_fix.
          - `closedAt` string, nullable, required
          - `closedNote` string, nullable, required
          - `createdAt` string, required
          - `updatedAt` string, required
          - `corrections` RunReviewCorrection[], required
            - `id` string, required
            - `kind` 'field' | 'file', required
            - `path` string, required — JSON Pointer for field corrections, or canonical artifact path for file reviews.
            - `label` string, nullable, required
            - `originalValue` unknown
            - `correctedValue` unknown
            - `note` string, required
            - `correctedArtifactPath` string, nullable
            - `createdAt` string, required
            - `updatedAt` string, required
        - `steps` unknown[], required — Per-step executions of the workflow run.
          - unknown
        - `definitionSnapshot` unknown
        - `expected` object — Ground-truth expected output and files.
          - `output` unknown
          - `files` RunFile[]
            - `name` string, required
      - AgentRunExecution
        - `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` RunReview
          - `id` string, required
          - `verdict` 'correct' | 'incorrect', nullable, required
          - `status` 'open' | 'closed' | 'wont_fix', required
          - `note` string, required
          - `correctedOutput` unknown
          - `reviewedBy` string, nullable, required — User id of the last reviewer. Read-only; set from the authenticated user or API key creator.
          - `reviewedByEmail` string, nullable, required — Email of the last reviewer. Read-only; set from the authenticated user or API key creator.
          - `reviewedAt` string, required
          - `closedBy` string, nullable, required — User id recorded when the review was closed. Read-only; set when status becomes closed or wont_fix.
          - `closedByEmail` string, nullable, required — Email recorded when the review was closed. Read-only; set when status becomes closed or wont_fix.
          - `closedAt` string, nullable, required
          - `closedNote` string, nullable, required
          - `createdAt` string, required
          - `updatedAt` string, required
          - `corrections` RunReviewCorrection[], required
            - `id` string, required
            - `kind` 'field' | 'file', required
            - `path` string, required — JSON Pointer for field corrections, or canonical artifact path for file reviews.
            - `label` string, nullable, required
            - `originalValue` unknown
            - `correctedValue` unknown
            - `note` string, required
            - `correctedArtifactPath` string, nullable
            - `createdAt` string, required
            - `updatedAt` string, required
        - `files` object, required
          - `output` RunFile[], required — Output artifacts the agent produced.
            - `name` string, required
        - `expected` object — Ground-truth expected output and files.
          - `output` unknown
          - `files` RunFile[]
            - `name` string, required
        - `comparison` unknown
  - `debug` RunDebug
    - `observability` unknown, required
    - `traceId` string, nullable — Workflow trace id for span lookup (workflow runs only).

## 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)