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 the stages the run went through, 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 (Pull request) and to an open decision (Open decision).

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. Retrying is recorded as run_state_changed.

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).