Skip to main content
GET/workflows/{wflId}/runs/{wfrId}

Get Workflow Run

Retrieves the full detail of a single workflow run by its wfr_<base62> identifier, including per-step status, per-action cost subtotals, and any error context.

Accessible to all Forge, Studio, and Workspace cohort roles subject to RLS.

Returns K9O_WORKFLOW_RUN_NOT_FOUND (404) if the run does not exist or is not within the caller's project scope.

Parameters
wflId *path

The workflow id (wfl_...).

wfrId *path

The run id (wfr_...), from the runs list or the response that started the run.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
401K9O_INVALID_CREDENTIALSThe request was made without a valid session or bearer token.
401K9O_SESSION_EXPIREDYour session has expired; re-authenticate and retry.
403K9O_ACCESS_DENIEDYour role does not include any Forge, Studio, or Workspace cohort permission required to read this run.
404K9O_WORKFLOW_NOT_FOUNDNo workflow with the supplied workflow ID exists in this project.
404K9O_WORKFLOW_RUN_NOT_FOUNDNo run with the supplied run ID exists for this workflow, or it is not within your project scope.
Response body (200)
data *object

One run of a workflow: its status, each started step's state and its cost.

id *string

The run id (wfr_...).

workflowId *string

The workflow that ran (wfl_...).

projectId *string

The project (proj_...).

status *"pending" | "running" | "succeeded" | "failed" | "cancelled"

pending until the runner picks it up, then running (which includes waiting on an approval), then succeeded, failed or cancelled.

Runs of one workflow go one at a time.

triggerContext *any

How the run was started: {trigger}, where trigger is manual, webhook, scheduled or form_submission, plus scheduledFor for a scheduled run.

The trigger's input is never returned.

perStepStatus *object[]

One entry per step that has started, in the order they started.

Empty for a pending run.

step_indexinteger

The step's index in the workflow.

action_typestring

What the step does.

statusstring

running, retrying, succeeded, skipped (its condition was false) or failed; or awaiting_<what> while the run waits, such as awaiting_approval.

attemptinteger

The attempt number of a retried step; 0 otherwise.

started_atstring <date-time>

When the step started.

completed_atstring <date-time>

When the step finished.

parked_atstring <date-time>

When the step began waiting.

retry_atstring <date-time>

When a retrying parallel step tries again.

last_reasonstring

Why the last attempt of a retrying step failed.

output_summaryobject

A short summary of what the step did, such as a row count.

It never holds the step's full output.

errorobject

Why the step failed.

Present on a failed step.

code *string

The error code.

reason *string

A fixed reason word.

costAccountingTotal *number

The run's metered cost.

errorContext *any

Why the run failed.

A failed step gives its code, a fixed reason word and the step index.

A run stopped because a collection it uses was erased gives reason record_erased and the collection.

Null unless the run failed.

One of: object
or: null
startedAt *string <date-time>

When the run was started (for a scheduled run, its slot).

completedAt *any

When the run ended.

Null while it is pending or running.

One of: string <date-time>
or: null
firedBy *string

Who or what started the run: the user's id for a manual run, system.webhook, system.scheduler or system.form otherwise.

meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.studio.workflows.runs.read('wfl_demo00000001', 'wfr_demo00000001')

Showing example in TypeScript

Response example (200)
{
  "data": {
    "id": "string",
    "workflowId": "string",
    "projectId": "string",
    "status": "pending",
    "perStepStatus": [
      {
        "step_index": 0,
        "action_type": "string",
        "status": "string",
        "attempt": 0,
        "started_at": "string",
        "completed_at": "string",
        "parked_at": "string",
        "retry_at": "string",
        "last_reason": "string",
        "error": {
          "code": "string",
          "reason": "string"
        }
      }
    ],
    "costAccountingTotal": 0,
    "startedAt": "string",
    "completedAt": "string",
    "firedBy": "string"
  }
}

More in Compute & Automation