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

List Workflow Runs

Returns the cursor-paginated history of execution runs for a workflow, ordered by start time descending.

Each run includes its status (pending, running, succeeded, failed, or cancelled), per-step status array, and aggregated cost.

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

Parameters
wflId *path

The workflow id (wfl_...).

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 list runs for this workflow.
404K9O_WORKFLOW_NOT_FOUNDNo workflow with the supplied ID exists in this project.
Response body (200)
data *object[]

The workflow's runs, newest first.

When more exist, meta.cursor.next holds the cursor for the next page; otherwise it is null.

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.list('wfl_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