Runs | kanman documentation

A run is kanman working on one story: planning, implementing, verifying and handing off. All attempts of one run share a run key such as run-7f3k. See Runs for the concept and The outcome gate and evidence for what the verification and the evidence pack contain. You follow and control runs in the app.

Your tools read runs through the REST API. Stopping and retrying stay in the app and the intake.

List runs

Open your team and the Runs tab (/<workspace>/teams/<team>/runs). Each run shows its story, run key, number of attempts, cost and status.

Read a run

The run page (/<workspace>/teams/<team>/runs/<run-key>) shows what the run is doing now, its steps with their checks and times, the progress updates under Progress, its attempts, the cost against the run budget, the evidence pack once the gates have run, and links to the pull request and to an open decision. Its tabs have addresses of their own: /steps, /evidence, /agent-log and /details after the run key, see The run page.

The same evidence pack is posted as a comment on the pull request and on the tracker issue.

Stop a run

On the run page, click Stop and confirm with Stop run. kanman stops the current attempt; the story stays where it is, and you can retry the run later. You can also ask kanman in the team’s intake, for example “cancel run-7f3k”. Stopping is recorded as run_state_changed.

Retry a run

A run that failed, timed out or was stopped can be started again with Retry on the run page. kanman queues a new attempt under the same run key; it uses the team’s policy as it is now, so a model or step budget you raised in the meantime already applies. If the last attempt ran out of steps, the button reads Retry with more steps and the new attempt gets the next class up with at least twice the steps, within your policy (see Ran out of steps). Retrying is recorded as run_state_changed, the model and steps the new attempt got as policy_decision.

REST API

List runs

GET /v1/runs returns the workspace’s runs, newest first, paginated. Filter with team (team slug) and story (story key).

curl "https://api.kanman.ai/functions/v1/api-gateway/v1/runs?team=sandbox-team" --header "Authorization: Bearer $KANMAN_API_KEY"

Field	Description
`key`, `team`, `story`	The run key, the team slug and the story (`key`, `title`).
`status`, `stage`	Status and stage of the latest attempt, for example `running` and `verifying`.
`executor`, `attempts`	The coding agent and the number of attempts.
`costCents`, `budgetCents`	Cost of all attempts and the run budget, in euro cents.
`failureClass`	Why the run stopped: `transient`, `persistent`, `policy`, `budget`, `gate` or `dependency`, otherwise `null`.
`pullRequest`	`url` and `number`, or `null`.
`startedAt`, `completedAt`, `createdAt`	Timestamps.

Read a run

GET /v1/runs/{run-key} returns one run with attemptList (per attempt: attempt, status, stage, executor, costCents, failureClass, error, verification, startedAt, completedAt), the evidence pack once the gates have run, and the run’s decisions (key, kind, status).