---
title: "Update workflow execution status"
method: PATCH
path: "/workflow_executions/{execution_id}"
tags: ["Workflows"]
---

# Update workflow execution status

`PATCH /workflow_executions/{execution_id}`

Manually update the status of a workflow execution. This is useful for programmatically controlling workflow lifecycle from external systems.

**Allowed status transitions:**
- `ended` - End the execution immediately
- `handoff` - Transfer execution to human agent
- `waiting` - Pause execution until resumed

**Use cases:**
- End workflows based on external events
- Transfer complex queries to human agents
- Implement custom timeout logic
- Coordinate workflows with external systems

Invalid transitions (e.g., transitioning from a terminal state) will return a 422 error with details about why the transition is not allowed.

**Response**: Returns full execution data including the updated status. Use GET /workflow_executions/{id} to retrieve execution context and event history.

## Request body

- WorkflowExecutionUpdateRequest — Request to update a workflow execution status. Only certain status transitions are allowed (ended, handoff, waiting). The execution will transition to the new status if the transition is valid according to the workflow state machine.
  - `workflow_execution` object, required
    - `status` 'ended' | 'handoff' | 'waiting', required — The new status for the workflow execution. Only specific transitions are allowed based on the current state.

## Response `200`

Execution status updated successfully

- WorkflowExecutionMinimalResponse — Minimal workflow execution response (without execution_context and events)
  - `data` WorkflowExecution, required — Base workflow execution schema
    - `id` string, uuid, required — Unique execution identifier
    - `status` 'running' | 'waiting' | 'ended' | 'failed' | 'handoff', required — Execution status: - `running`: Currently executing workflow steps - `waiting`: Paused, awaiting user input or timeout - `ended`: Successfully completed - `failed`: Terminated due to error - `handoff`: Transferred to human agent
    - `started_at` string, date-time, required — Execution start timestamp
    - `ended_at` string, date-time, nullable — Execution completion timestamp, null if still active
    - `last_event_at` string, date-time, required — Timestamp of most recent workflow event or activity
    - `tracking_id` string, uuid, nullable — Optional external tracking identifier for correlating with external systems
    - `whatsapp_conversation_id` string, uuid, nullable — Associated WhatsApp conversation identifier, links execution to its conversation
    - `workflow` WorkflowMinimal — Compact workflow reference used in execution objects
      - `id` string, uuid, required — Workflow identifier
      - `name` string, required — Workflow name
      - `status` string, required — Workflow status
    - `current_step` WorkflowStepReference — Reference to a workflow step (used in execution current_step tracking)
      - `id` string, uuid, required — Internal ID of the workflow step
      - `identifier` string, required — Step identifier within the workflow (e.g., 'start', 'step1', 'agent_greeting')
      - `stepable_type` string, nullable — Ruby class name of the step type (e.g., 'FlowAgentStep', 'FlowActionStep', 'FlowWaitStep', 'FlowDecideStep')
      - `position` object, nullable — Canvas position for visual editor
        - `x` number
        - `y` number
    - `error_details` object, nullable — Error information when status is 'failed' (error message, stack trace, step identifier)

## Other responses

- `400` — Missing or invalid request body
- `401` — Missing or invalid API key
- `404` — Resource not found
- `422` — Invalid status transition

---

[API](https://skmtc.net/kapso/apis/kapso-platform-api.md) · [All operations](https://skmtc.net/kapso/apis/kapso-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kapso/kapso-platform-api/revisions/18ff5548a33f/schema)