> ## Documentation Index > Fetch the complete documentation index at: https://docs.kiwiflow.io/llms.txt > Use this file to discover all available pages before exploring further. # Running work > Start a run, follow its steps, make decisions, request rework, hand off or cancel, and retry safely. A run takes one piece of work through one workflow revision. Open a project's **Runs** tab to start runs and see active and past ones. ## Start a run In **Runs**, fill in the form and choose **Start run**. An agent can start a run with `start_run`, using the matching fields: | App field | `start_run` field | If left out | | - | - | - | | Workflow | `workflowId`, `workflowRevision` | The latest published revision | | What needs doing? | `requestText` | At least one of these two is required | | Link (optional) | `requestReference` | | | Owner | `responsibleUserId` | You | | Approves the plan | `designatedOwnerId` | You | | Approves the result | `designatedReviewerId` | You | For an agent, "you" is the person who signed the agent in, or the Admin who issued its [MCP key](https://docs.kiwiflow.io/team-and-billing.md#mcp-keys). Set the people explicitly when someone else should decide. * **Owner** is responsible for the run. Handed-off steps go to the Owner, and the Owner can cancel the run. * **Approves the plan** and **Approves the result** need a project role allowed on that step. In Development, the person who approves the result must be an Admin or Reviewer. * The person starting the run must be allowed to do the first step. `start_run` returns `400 ineligible_decision_maker` when an approver lacks an allowed role, `400 invalid_responsible_user` when the Owner is not a project member, and `404 workflow_not_found` when the workflow or revision is not published. ## Follow a run The run page shows each step's state, its attempts, check results, who did what, and the actions open to you. Agents read the same information with `get_run`. | Run status | Meaning | | - | - | | `active` | Work can continue | | `blocked` | A step is blocked; see [Blockers](#blockers-and-handoffs) | | `completed` | Every step is accepted | | `cancelled` | The run was cancelled | | Step status | Meaning | | - | - | | `locked` | An earlier step is not accepted yet | | `ready` | The step can be started | | `in_progress` | Someone is working on it | | `submitted` | Outputs are in and waiting for a decision | | `accepted` | The step is done | | `failed` | A check or review failed; rework is needed | | `blocked` | Work stopped; see [Blockers](#blockers-and-handoffs) | | `cancelled` | The run was cancelled during this step | `nextActions` lists what the current person or agent can do now: `start_step`, `submit_step`, `decide_step`, `report_blocker`, `handoff_step`, `report_check`, `request_rework` or `cancel_run`. Act on it rather than on someone's role. Accepting one step makes the next one ready. Kiwi does not start the next step for you. ## Decisions Only people make decisions, and only in the app. * **Approve the plan.** When the Plan step is submitted, the person in **Approves the plan** accepts it or sends it back with a reason. Sending it back reopens Plan. * **Approve the result.** When Human acceptance is submitted, the person in **Approves the result** accepts it or requests rework with a reason. Agents can submit the Plan step, but they cannot approve it, and they cannot submit or approve Human acceptance. ## Rework After the plan is accepted, an Admin or Reviewer can request rework from the run page with a reason. By default rework returns the run to Implement and keeps the accepted plan. Choose to revise the plan to return to Plan instead. Rework clears the current candidate. Earlier check results and reviews stay in the history but no longer count; run the checks and review again for the new candidate. A failed check, a `blocked` or `not-applicable` check, or a review verdict other than `pass` needs rework. ## Blockers and handoffs * **Blocker.** Whoever is working on a step can report a blocker with a reason (`report_blocker`). Only the same person, or the same agent session, can resume it by starting the step again with the same attempt ID. * **Handoff.** Whoever is working on a step can hand it to the run's Owner with notes (`handoff_step`). Kiwi creates a new attempt that only the Owner can start, in the app. The **Handoff** step at the end of a workflow is different: it records where the finished work was delivered. ## Cancel a run The Owner or a project Admin can cancel a run from the run page with a reason. Cancelling stops Kiwi from accepting further changes to the run. It does not stop agents, CI jobs or anything else running outside Kiwi. ## Retries Every change to a run carries a command ID and the current run version: `commandId` and `expectedRunVersion` in MCP, `command_id` and `expected_run_version` in the checker API. Kiwi records a command ID once. Sending the same command again returns the original result instead of recording it twice. | What happened | What to do | | - | - | | The connection dropped or timed out with no error | Send the identical command again with the same command ID. | | `400`, `401`, `403` or `404` | Kiwi rejected it. Fix the request or access, then send a new command ID. | | `409` | The run changed. Read it again, then send a new command ID with the current version and attempt. | | `500` | The outcome is unknown. Send the identical command again with the same command ID. | | `503` | A service Kiwi depends on is unavailable. Check the run before trying again. | Never reuse a command ID with different content; Kiwi returns `409 idempotency_conflict`. See [Error codes](https://docs.kiwiflow.io/troubleshooting.md#error-codes) for each code. **Attempt IDs.** When a ready step has no current attempt, create a new UUID as its attempt ID. After that, use the attempt ID Kiwi returns. Attempt IDs cannot be reused. ## Activity The project's **Activity** tab lists everything recorded across its runs: steps started and submitted, decisions, check results, blockers, handoffs, rework and cancellations. Filter by run or event type, and open a run from any event. Activity shows only what was reported to Kiwi. It does not include agent transcripts, CI logs or work nobody reported. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.