Skip to main content
POST
/
api
/
v1
/
execute
curl -X POST https://your-worker.workers.dev/api/v1/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ensemble": "order-processing",
    "input": {
      "orderId": "ORD-123",
      "customerId": "CUST-456"
    }
  }'
{
  "id": "exec_abc123def456",
  "status": "completed",
  "output": {
    "status": "success",
    "total": 99.99,
    "paymentId": "ch_1234567890"
  },
  "duration": 1523,
  "timestamp": 1704067200000
}

Execute Ensemble

ensemble
string
required
Name of the ensemble to execute
input
object
Input data for the ensemble
async
boolean
default:"false"
Execute asynchronously and return execution ID immediately
timeout
number
default:"30000"
Maximum execution time in milliseconds
stream
boolean
default:"false"
Stream execution progress via Server-Sent Events

Response

id
string
Unique execution identifier
status
string
Execution status: completed, failed, running, waiting_for_input
output
object
Ensemble output data (if completed)
error
object
Error details (if failed)
duration
number
Execution time in milliseconds
timestamp
number
Unix timestamp of execution start
curl -X POST https://your-worker.workers.dev/api/v1/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ensemble": "order-processing",
    "input": {
      "orderId": "ORD-123",
      "customerId": "CUST-456"
    }
  }'
{
  "id": "exec_abc123def456",
  "status": "completed",
  "output": {
    "status": "success",
    "total": 99.99,
    "paymentId": "ch_1234567890"
  },
  "duration": 1523,
  "timestamp": 1704067200000
}

Get Execution Status

Retrieve the status and result of a specific execution.
id
string
required
Execution ID returned from execute endpoint

Response

id
string
Execution identifier
status
string
Current status: completed, failed, running, waiting_for_input
output
object
Result data (if completed)
error
object
Error information (if failed)
progress
object
Execution progress information
progress.completed
number
Number of completed members
progress.total
number
Total number of members
progress.current
string
Currently executing member name
curl https://your-worker.workers.dev/api/v1/executions/exec_abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "id": "exec_abc123def456",
  "status": "running",
  "progress": {
    "completed": 3,
    "total": 7,
    "current": "process-payment"
  },
  "timestamp": 1704067200000
}

Resume Execution

Resume a workflow waiting for human input (HITL).
id
string
required
Execution ID
token
string
required
HITL token from execution status
input
object
required
Human input data matching the HITL fields
curl -X POST https://your-worker.workers.dev/api/v1/executions/exec_abc123/resume \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "hitl_xyz789",
    "input": {
      "approved": true,
      "comments": "Looks good"
    }
  }'
{
  "id": "exec_abc123def456",
  "status": "completed",
  "output": {
    "approved": true,
    "result": "published"
  },
  "duration": 3522,
  "timestamp": 1704067200000
}

Cancel Execution

Cancel a running execution.
id
string
required
Execution ID to cancel
curl -X DELETE https://your-worker.workers.dev/api/v1/executions/exec_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "id": "exec_abc123def456",
  "status": "cancelled",
  "message": "Execution cancelled successfully"
}

Stream Execution

Execute an ensemble and stream progress updates via Server-Sent Events (SSE).
ensemble
string
required
Ensemble name
input
object
Input data

Event Types

EventDescription
startExecution started
member.startMember execution started
member.completeMember execution completed
member.errorMember execution failed
hitl.waitingWaiting for human input
completeExecution completed
errorExecution failed
const eventSource = new EventSource(
  'https://your-worker.workers.dev/api/v1/stream',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ensemble: 'order-processing',
      input: { orderId: 'ORD-123' }
    })
  }
);

eventSource.addEventListener('member.complete', (event) => {
  const data = JSON.parse(event.data);
  console.log(`Completed: ${data.member}`);
});

eventSource.addEventListener('complete', (event) => {
  const data = JSON.parse(event.data);
  console.log('Final output:', data.output);
  eventSource.close();
});

eventSource.addEventListener('error', (event) => {
  console.error('Stream error:', event);
  eventSource.close();
});
event: start
data: {"id":"exec_abc123","timestamp":1704067200000}

event: member.start
data: {"member":"validate-order","timestamp":1704067200100}

event: member.complete
data: {"member":"validate-order","duration":123,"timestamp":1704067200223}

event: member.start
data: {"member":"process-payment","timestamp":1704067200250}

event: member.complete
data: {"member":"process-payment","duration":1200,"output":{"paymentId":"ch_123"},"timestamp":1704067201450}

event: complete
data: {"id":"exec_abc123","status":"completed","output":{"total":99.99},"duration":1523,"timestamp":1704067201523}

Error Codes

CodeDescriptionResolution
VALIDATION_ERRORInvalid input dataCheck input schema
ENSEMBLE_NOT_FOUNDEnsemble doesn’t existVerify ensemble name
EXECUTION_NOT_FOUNDExecution ID not foundCheck execution ID
INVALID_TOKENHITL token invalid/expiredRequest new token
TIMEOUTExecution exceeded timeoutIncrease timeout or optimize workflow
RATE_LIMIT_EXCEEDEDToo many requestsImplement backoff, increase limits