Workflows

Retrieve workflow execution

Get complete details for a workflow execution including current status, execution context, variables, and full event history.

This is the only endpoint that returns the full execution_context (vars, system, context, metadata) along with the complete event history.

Use this endpoint to:

Monitor execution progress and current step
Debug failed executions with full event log
Review execution variables and context
Check error details when status is ‘failed’

The response includes:

Current status and step
Complete event chronology (step transitions, agent actions, variable updates)
Full execution_context with standard structure (vars, system, context, metadata)
Error details if execution failed

GET

workflow_executions

{execution_id}

Retrieve workflow execution

curl --request GET \
  --url https://api.kapso.ai/platform/v1/workflow_executions/{execution_id} \
  --header 'X-API-Key: <api-key>'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "started_at": "2023-11-07T05:31:56Z",
    "last_event_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z",
    "tracking_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "whatsapp_conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workflow": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "status": "<string>"
    },
    "current_step": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "identifier": "<string>",
      "stepable_type": "<string>",
      "position": {
        "x": 123,
        "y": 123
      }
    },
    "error_details": {},
    "execution_context": {
      "vars": {
        "lead_id": 123,
        "last_user_input": {
          "button_id": "yes"
        }
      },
      "system": {
        "trigger_type": "api_call",
        "tracking_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      },
      "context": {
        "channel": "api",
        "phone_number": "+15551234567"
      },
      "metadata": {
        "request": {
          "ip": "<string>",
          "user_agent": "<string>",
          "timestamp": "2023-11-07T05:31:56Z"
        }
      }
    },
    "events": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "event_type": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "direction": "<string>",
        "edge_label": "<string>",
        "payload": {},
        "step": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "identifier": "<string>",
          "stepable_type": "<string>",
          "position": {
            "x": 123,
            "y": 123
          }
        }
      }
    ]
  }
}

Authorizations

X-API-Key

string

header

required

Path Parameters

execution_id

string<uuid>

required

Execution identifier

Response

Execution details retrieved successfully

Single workflow execution with full details

data

object

required

Detailed execution with full context and event history (only returned by show endpoint)

Show child attributes

Update workflow execution statusManually 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.

Retrieve workflow execution

curl --request GET \
  --url https://api.kapso.ai/platform/v1/workflow_executions/{execution_id} \
  --header 'X-API-Key: <api-key>'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "started_at": "2023-11-07T05:31:56Z",
    "last_event_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z",
    "tracking_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "whatsapp_conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workflow": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "status": "<string>"
    },
    "current_step": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "identifier": "<string>",
      "stepable_type": "<string>",
      "position": {
        "x": 123,
        "y": 123
      }
    },
    "error_details": {},
    "execution_context": {
      "vars": {
        "lead_id": 123,
        "last_user_input": {
          "button_id": "yes"
        }
      },
      "system": {
        "trigger_type": "api_call",
        "tracking_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      },
      "context": {
        "channel": "api",
        "phone_number": "+15551234567"
      },
      "metadata": {
        "request": {
          "ip": "<string>",
          "user_agent": "<string>",
          "timestamp": "2023-11-07T05:31:56Z"
        }
      }
    },
    "events": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "event_type": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "direction": "<string>",
        "edge_label": "<string>",
        "payload": {},
        "step": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "identifier": "<string>",
          "stepable_type": "<string>",
          "position": {
            "x": 123,
            "y": 123
          }
        }
      }
    ]
  }
}