Overview
Execute workflows programmatically and monitor their progress and results.
Base URL: https://api.so1.io/v1/n8n/executions
Execute Workflow
Endpoint
POST /v1/n8n/workflows/{workflowId}/execute
Request Body
Input data for workflow trigger node
Execution mode: async (immediate return) or sync (wait for completion)
Maximum execution time in seconds (sync mode only)
Example Request
curl -X POST https://api.so1.io/v1/n8n/workflows/deploy-notification/execute \
-H "Authorization: Bearer so1_key_abc123xyz" \
-H "Content-Type: application/json" \
-d '{
"data": {
"service": "api-gateway",
"environment": "production",
"version": "v2.4.1"
},
"mode": "async"
}'
Response (Async)
{
"success": true,
"data": {
"executionId": "exec-abc123",
"workflowId": "deploy-notification",
"status": "running",
"startedAt": "2024-03-10T15:30:00Z"
}
}
Response (Sync - Completed)
{
"success": true,
"data": {
"executionId": "exec-abc123",
"workflowId": "deploy-notification",
"status": "success",
"result": {
"slackMessageSent": true,
"notificationId": "msg-xyz789"
},
"startedAt": "2024-03-10T15:30:00Z",
"finishedAt": "2024-03-10T15:30:02.3Z",
"duration": 2.3
}
}
Get Execution Status
Endpoint
GET /v1/n8n/executions/{executionId}
Query Parameters
Include full node input/output data
Response (Running)
{
"success": true,
"data": {
"executionId": "exec-abc123",
"workflowId": "deploy-notification",
"workflowName": "Deploy Notification",
"status": "running",
"progress": {
"nodesCompleted": 2,
"nodesTotal": 5,
"currentNode": "Send Email"
},
"startedAt": "2024-03-10T15:30:00Z",
"estimatedCompletionAt": "2024-03-10T15:30:05Z"
}
}
Response (Completed with Data)
{
"success": true,
"data": {
"executionId": "exec-abc123",
"workflowId": "deploy-notification",
"status": "success",
"result": {
"success": true,
"outputs": {
"slackMessageSent": true,
"emailSent": true
}
},
"nodeData": [
{
"nodeName": "Webhook",
"nodeType": "n8n-nodes-base.webhook",
"status": "success",
"duration": 0.1,
"output": {
"service": "api-gateway",
"environment": "production"
}
},
{
"nodeName": "Send Slack Message",
"nodeType": "n8n-nodes-base.slack",
"status": "success",
"duration": 1.2,
"output": {
"messageId": "msg-xyz789",
"channel": "#deployments"
}
}
// ... more nodes
],
"duration": 2.3,
"startedAt": "2024-03-10T15:30:00Z",
"finishedAt": "2024-03-10T15:30:02.3Z"
}
}
Response (Failed)
{
"success": true,
"data": {
"executionId": "exec-abc123",
"status": "error",
"error": {
"message": "Slack API error: channel_not_found",
"node": "Send Slack Message",
"nodeType": "n8n-nodes-base.slack",
"details": {
"httpStatus": 404,
"slackError": "channel_not_found"
}
},
"startedAt": "2024-03-10T15:30:00Z",
"failedAt": "2024-03-10T15:30:01.5Z",
"duration": 1.5
}
}
List Executions
Endpoint
Query Parameters
Filter by status: running, success, error, waiting, canceled
ISO 8601 date - filter executions after this date
ISO 8601 date - filter executions before this date
Response
{
"success": true,
"data": {
"executions": [
{
"executionId": "exec-abc123",
"workflowId": "deploy-notification",
"workflowName": "Deploy Notification",
"status": "success",
"duration": 2.3,
"startedAt": "2024-03-10T15:30:00Z",
"finishedAt": "2024-03-10T15:30:02.3Z"
}
// ... more executions
],
"pagination": {
"total": 1247,
"limit": 20,
"hasMore": true
}
}
}
Retry Failed Execution
Endpoint
POST /v1/n8n/executions/{executionId}/retry
Request Body
Retry from specific node (optional, defaults to failed node)
Response
{
"success": true,
"data": {
"executionId": "exec-new456",
"originalExecutionId": "exec-abc123",
"status": "running",
"startedAt": "2024-03-10T15:35:00Z"
}
}
Cancel Execution
Endpoint
POST /v1/n8n/executions/{executionId}/cancel
Response
{
"success": true,
"data": {
"executionId": "exec-abc123",
"status": "canceled",
"canceledAt": "2024-03-10T15:35:00Z"
}
}
Delete Execution
Endpoint
DELETE /v1/n8n/executions/{executionId}
Response
{
"success": true,
"data": {
"executionId": "exec-abc123",
"deletedAt": "2024-03-10T15:35:00Z"
}
}
Get Execution Logs
Endpoint
GET /v1/n8n/executions/{executionId}/logs
Response
{
"success": true,
"data": {
"executionId": "exec-abc123",
"logs": [
{
"timestamp": "2024-03-10T15:30:00.000Z",
"level": "info",
"message": "Workflow execution started"
},
{
"timestamp": "2024-03-10T15:30:00.100Z",
"level": "info",
"node": "Webhook",
"message": "Received webhook data"
},
{
"timestamp": "2024-03-10T15:30:01.200Z",
"level": "info",
"node": "Send Slack Message",
"message": "Slack message sent successfully"
},
{
"timestamp": "2024-03-10T15:30:02.300Z",
"level": "info",
"message": "Workflow execution completed successfully"
}
]
}
}
Common Patterns
Poll for Completion
async function waitForWorkflowCompletion(executionId: string): Promise<any> {
const maxAttempts = 60; // 5 minutes
for (let attempt = 0; attempt < maxAttempts; attempt++) {
const response = await fetch(
`https://api.so1.io/v1/n8n/executions/${executionId}`,
{ headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
const { data } = await response.json();
if (data.status === 'success') {
return data.result;
} else if (data.status === 'error') {
throw new Error(data.error.message);
}
await new Promise(resolve => setTimeout(resolve, 5000));
}
throw new Error('Workflow timeout');
}
Retry with Exponential Backoff
async function retryFailedExecution(
executionId: string,
maxRetries: number = 3
): Promise<string> {
for (let attempt = 0; attempt < maxRetries; attempt++) {
const response = await fetch(
`https://api.so1.io/v1/n8n/executions/${executionId}/retry`,
{
method: 'POST',
headers: { 'Authorization': `Bearer ${API_KEY}` }
}
);
const { data } = await response.json();
const result = await waitForWorkflowCompletion(data.executionId);
if (result.success) {
return data.executionId;
}
// Exponential backoff before next retry
const delay = Math.pow(2, attempt) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
}
throw new Error('Max retries exceeded');
}
