# Run Workflow

`POST /workflows/{wflId}/runs` · Core · Compute & Automation

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

| Name | In | Required | Description |
|---|---|---|---|
| `wflId` | path | yes | The workflow id (`wfl_...`). Example: `"wfl_demo00000001"`. |
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `triggerContext` | object | no | The run's input, which templates read as `{{trigger.<field>}}`. It is kept private to the run and is not returned. Default `{}`. |

```json
{
  "triggerContext": null
}
```

## Responses

- **202**: The 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.

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | One run of a workflow: its status, each started step's state and its cost. |
| `data.id` | string | yes | The run id (`wfr_...`). |
| `data.workflowId` | string | yes | The workflow that ran (`wfl_...`). |
| `data.projectId` | string | yes | The project (`proj_...`). |
| `data.status` | enum ("pending", "running", "succeeded", "failed", "cancelled") | yes | `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. |
| `data.triggerContext` | object | yes | 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. |
| `data.perStepStatus` | array of object | yes | One entry per step that has started, in the order they started. Empty for a pending run. |
| `data.perStepStatus.[]step_index` | integer | no | The step's index in the workflow. |
| `data.perStepStatus.[]action_type` | string | no | What the step does. |
| `data.perStepStatus.[]status` | string | no | `running`, `retrying`, `succeeded`, `skipped` (its condition was false) or `failed`; or `awaiting_<what>` while the run waits, such as `awaiting_approval`. |
| `data.perStepStatus.[]attempt` | integer | no | The attempt number of a retried step; 0 otherwise. |
| `data.perStepStatus.[]started_at` | string (date-time) | no | When the step started. |
| `data.perStepStatus.[]completed_at` | string (date-time) | no | When the step finished. |
| `data.perStepStatus.[]parked_at` | string (date-time) | no | When the step began waiting. |
| `data.perStepStatus.[]retry_at` | string (date-time) | no | When a retrying parallel step tries again. |
| `data.perStepStatus.[]last_reason` | string | no | Why the last attempt of a retrying step failed. |
| `data.perStepStatus.[]output_summary` | object | no | A short summary of what the step did, such as a row count. It never holds the step's full output. |
| `data.perStepStatus.[]error` | object | no | Why the step failed. Present on a failed step. |
| `data.perStepStatus.[]error.code` | string | yes | The error code. |
| `data.perStepStatus.[]error.reason` | string | yes | A fixed reason word. |
| `data.costAccountingTotal` | number | yes | The run's metered cost. |
| `data.errorContext` | object | yes | 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_ | | |  |
| _or_ | | |  |
| `data.startedAt` | string (date-time) | yes | When the run was started (for a scheduled run, its slot). |
| `data.completedAt` | object | yes | When the run ended. Null while it is pending or running. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.firedBy` | string | yes | Who or what started the run: the user's id for a manual run, `system.webhook`, `system.scheduler` or `system.form` otherwise. |
| `meta` | object | yes |  |


## Errors

| HTTP | Code | When |
|---|---|---|
| 401 | `K9O_INVALID_CREDENTIALS` | The request was made without a valid session or bearer token. |
| 401 | `K9O_SESSION_EXPIRED` | Your session has expired; re-authenticate and retry. |
| 403 | `K9O_ACCESS_DENIED` | Manually triggering a workflow run requires the PROJECT_AUTHOR role; your current role does not grant it. |
| 404 | `K9O_WORKFLOW_NOT_FOUND` | No workflow with the supplied ID exists in this project. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/workflows/wfl_demo00000001/runs' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "triggerContext": null
}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/workflows/wfl_demo00000001/runs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "triggerContext": null
}),
});
const { data, meta } = await res.json();
```

### @k9o/core

```typescript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.studio.workflows.trigger('wfl_demo00000001', {
  triggerContext: null
})
```

### k9o

```python
# k9o = create_client(org_slug="playground", project_slug="storefront", api_key="k9o_…")
response = k9o.studio.workflows.trigger("wfl_demo00000001", {
    "triggerContext": None
})
```

### sdk-go

```go
// ctx := context.Background()
// client, _ := k9o.NewClient(k9o.ClientOpts{OrgSlug: "playground", ProjectSlug: "storefront", APIKey: "k9o_…"})
data, _, kerr := client.Studio.Workflows.Trigger(ctx, "wfl_demo00000001", map[string]any{"triggerContext": nil})
```

### k9o

```rust
// let k9o = Client::new(ClientOpts { org_slug: "playground".into(), project_slug: "storefront".into(), api_key: "k9o_…".into() })?;
let resp = k9o.studio.workflows.trigger("wfl_demo00000001", json!({"triggerContext": null})).await?
```

### dev.k9o:core

```java
// K9o k9o = K9o.createClient(K9o.Opts.builder().orgSlug("playground").projectSlug("storefront").apiKey("k9o_…").build());
var response = k9o.studio().workflows().trigger("wfl_demo00000001", Map.of("triggerContext", null))
```

### K9o.Core

```c#
// var k9o = K9oClient.Create(new K9oOptions { OrgSlug = "playground", ProjectSlug = "storefront", ApiKey = "k9o_…" });
var response = await k9o.Studio.Workflows.TriggerAsync("wfl_demo00000001", new Dictionary<string, object> { ["triggerContext"] = null })
```

### k9o

```ruby
# k9o = K9o.create_client(org_slug: "playground", project_slug: "storefront", api_key: "k9o_…")
response = k9o.studio.workflows.trigger("wfl_demo00000001", { triggerContext: nil })
```

### k9o/sdk

```php
// $k9o = K9oClient::create(['org_slug' => 'playground', 'project_slug' => 'storefront', 'api_key' => 'k9o_…']);
$response = $k9o->studio->workflows->trigger('wfl_demo00000001', ['triggerContext' => null])
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/run-workflow
