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

Run Workflow

Manually triggers a new execution run for a workflow whose trigger_type is manual, returning a run record with status: 'pending'.

Requires the PROJECT_AUTHOR role.

Parameters
wflId *path

The workflow id (wfl_...).

projectSlug *path

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

It is unique within the org.

Request body
triggerContextany

The run's input, which templates read as {{trigger.<field>}}.

It is kept private to the run and is not returned.

Default {}.

Responses
HTTPK9O CodeDescription
202The run was queued and comes back `pending`; the runner executes it in the background. Poll the run, or subscribe to `studio.workflows.runs.<workflow id>`, to follow it.
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_DENIEDManually triggering a workflow run requires the PROJECT_AUTHOR role; your current role does not grant it.
404K9O_WORKFLOW_NOT_FOUNDNo workflow with the supplied ID exists in this project.
Response body (202)
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.trigger('wfl_demo00000001', {
  triggerContext: null
})

Showing example in TypeScript

Request example
{
  "triggerContext": null
}
Response example (202)
{
  "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