Execution

Workflows execute on a durable backend that supports long-running processes, human-in-the-loop interactions, and step-by-step progress tracking.

Execution Flow

When you execute a workflow:

Start - Workflow begins at the initialStep
Execute Steps - Each step runs in sequence following edges
Pause (optional) - Workflow pauses for human input or approval
Resume - Continue after receiving input
Complete - Workflow reaches end-flow step

Synchronous vs Asynchronous

Synchronous Execution:

POST /api/workflow/start/:workflowId

Blocks until workflow completes
Returns final result directly
Best for quick workflows without pauses

Asynchronous Execution:

POST /api/workflow/start-async/:workflowId

Returns immediately with runId
Poll status endpoint for progress
Required for workflows with human steps

Monitoring Progress

Poll the status endpoint to track execution:

curl https://service.ensembleapp.ai/api/workflow/status/${RUN_ID} \
  -H "x-api-key: sk_your_api_key" \
  -H "x-tenant-id: your_tenant_id"

Response:

{
  "runId": "dynamic-workflow-1705779900000",
  "status": "running",
  "currentStepId": "send-email-1",
  "stepExecutionHistory": [
    {
      "stepId": "collect-inputs-1",
      "stepType": "collect-inputs",
      "status": "completed",
      "duration": 5000,
      "outputData": {"customerName": "John Doe"}
    },
    {
      "stepId": "send-email-1",
      "stepType": "call-tool",
      "status": "running",
      "startTime": "2024-01-20T15:45:05Z"
    }
  ]
}

Execution Status

Status	Description
`running`	Workflow is actively executing
`completed`	Workflow finished successfully
`failed`	Workflow encountered an error
`paused`	Waiting for human input or action

Handling Pauses

Workflows pause when they reach steps requiring human interaction:

Collect Inputs Pause

The workflow needs data from a user:

{
  "status": "paused",
  "pauseSignal": {
    "type": "collect_inputs",
    "stepId": "approval-inputs",
    "fields": {
      "approvalReason": {"type": "string"},
      "approvedAmount": {"type": "number"}
    }
  }
}

Resume with data:

curl -X POST https://service.ensembleapp.ai/api/workflow/resume/${RUN_ID} \
  -H "x-api-key: sk_your_api_key" \
  -H "x-tenant-id: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "collect_inputs",
    "data": {
      "approvalReason": "Budget approved for Q1",
      "approvedAmount": 10000
    }
  }'

User Action Pause

The workflow needs a decision (approve/reject):

{
  "status": "paused",
  "pauseSignal": {
    "type": "request_user_action",
    "stepId": "manager-approval",
    "actions": [
      {"id": "approve", "label": "Approve"},
      {"id": "reject", "label": "Reject"}
    ]
  }
}

Resume with action:

curl -X POST https://service.ensembleapp.ai/api/workflow/resume/${RUN_ID} \
  -H "x-api-key: sk_your_api_key" \
  -H "x-tenant-id: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "request_user_action",
    "actionId": "approve",
    "actionValue": "approved"
  }'

Step Execution History

Each step in stepExecutionHistory includes:

Field	Description
`stepId`	Unique step identifier
`stepType`	Type of step (collect-inputs, call-tool, etc.)
`stepName`	Human-readable step name
`status`	Step status: `running`, `completed`, `failed`
`startTime`	ISO 8601 start timestamp
`endTime`	ISO 8601 end timestamp (if completed)
`duration`	Execution time in milliseconds
`inputData`	Data provided to the step
`outputData`	Data produced by the step
`error`	Error message (if failed)

Cancellation and Termination

Cancel - Request graceful shutdown:

curl -X POST https://service.ensembleapp.ai/api/workflow/management/cancel \
  -H "x-api-key: sk_your_api_key" \
  -H "x-tenant-id: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "customer-onboarding",
    "runId": "dynamic-workflow-1705779900000",
    "reason": "User requested cancellation"
  }'

Terminate - Force-kill immediately:

curl -X POST https://service.ensembleapp.ai/api/workflow/management/terminate \
  -H "x-api-key: sk_your_api_key" \
  -H "x-tenant-id: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "customer-onboarding",
    "runId": "dynamic-workflow-1705779900000",
    "reason": "Workflow unresponsive"
  }'

Action	Behavior
Cancel	Graceful shutdown, allows cleanup
Terminate	Immediate stop, no cleanup

Passing Initial Data

Provide input data when starting a workflow:

curl -X POST https://service.ensembleapp.ai/api/workflow/start/${WORKFLOW_ID} \
  -H "x-api-key: sk_your_api_key" \
  -H "x-tenant-id: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "vendorId": "vendor-123",
      "budget": 50000,
      "department": "Engineering",
      "priority": "high"
    }
  }'

The workflow can access this data in step configurations using ${data.fieldName} syntax.

Error Handling

When a step fails, the workflow status becomes failed:

{
  "status": "failed",
  "stepExecutionHistory": [
    {
      "stepId": "call-api-1",
      "status": "failed",
      "error": "Connection timeout to external service"
    }
  ]
}

The execution backend provides automatic retries for transient failures. Permanent failures stop the workflow and record the error.

Durability

Workflows are durable and survive:

Server restarts
Deployments
Network interruptions

Paused workflows can remain paused indefinitely until resumed. All execution state is persisted and recoverable.

On this page