# Executions API Reference
Complete API reference for execution management operations. Monitor, debug, and retry workflow executions across instances.
---
## Overview
The Executions API provides programmatic access to workflow execution history, detailed execution data, and retry capabilities.
**Available Operations:**
| Operation | Purpose | Common Use Cases |
|-----------|---------|------------------|
| `list_executions` | List execution history | Monitoring, debugging, analytics |
| `get_execution` | Get detailed execution data | Root cause analysis, debugging |
| `delete_execution` | Remove execution records | Cleanup, compliance |
| `retry_execution` | Retry failed executions | Error recovery, reprocessing |
---
## list_executions
List workflow execution history with filtering and cursor-based pagination.
### Purpose
Retrieve execution records for monitoring, debugging, analytics, and compliance. Supports comprehensive filtering by workflow, status, and time ranges.
### Use Cases
- Building execution monitoring dashboards
- Tracking workflow success/failure rates
- Finding failed executions for retry
- Debugging specific workflow runs
- Compliance and audit reporting
- Performance analysis
---
### Request
**MCP Tool Name:** `list_executions`
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| instance | string | No | default | Instance identifier |
| workflowId | string | No | - | Filter by workflow ID |
| finished | boolean | No | - | Filter by completion status |
| status | string | No | - | Filter by status: 'success', 'error', 'waiting' |
| includeData | boolean | No | false | Include execution data (slower, larger response) |
| limit | number | No | 100 | Max executions (1-250) |
| cursor | string | No | - | Pagination cursor |
**TypeScript Interface:**
```typescript
interface ListExecutionsParams {
instance?: string;
workflowId?: string;
finished?: boolean;
status?: 'success' | 'error' | 'waiting';
includeData?: boolean;
limit?: number; // Range: 1-250
cursor?: string;
}
```
**JSON-RPC Request Example:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_executions",
"arguments": {
"instance": "production",
"workflowId": "123",
"finished": true,
"status": "error",
"limit": 50
}
}
}
```
---
### Response
**Success Response:**
**TypeScript Interface:**
```typescript
interface ExecutionListResponse {
data: ExecutionSummary[];
nextCursor?: string;
}
interface ExecutionSummary {
id: number;
workflowId: number;
finished: boolean;
mode: ExecutionMode;
startedAt: string; // ISO 8601 timestamp
stoppedAt?: string; // ISO 8601 timestamp
retryOf?: number; // If this is a retry
retrySuccessId?: number; // If retry succeeded
}
type ExecutionMode =
| 'manual' // Manual execution via UI
| 'trigger' // Triggered automatically
| 'webhook' // Webhook execution
| 'retry' // Retry of previous execution
| 'cli' // CLI execution
| 'error' // Error workflow execution
| 'integrated' // Integrated workflow
| 'internal'; // Internal execution
```
**JSON Example:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [{
"type": "text",
"text": "{
\"data\": [
{
\"id\": 9876,
\"workflowId\": 123,
\"finished\": true,
\"mode\": \"webhook\",
\"startedAt\": \"2025-01-15T10:30:00.000Z\",
\"stoppedAt\": \"2025-01-15T10:30:02.245Z\"
},
{
\"id\": 9875,
\"workflowId\": 123,
\"finished\": false,
\"mode\": \"manual\",
\"startedAt\": \"2025-01-15T10:25:00.000Z\"
}
],
\"nextCursor\": \"eyJvZmZzZXQiOjEwMH0=\"
}"
}]
}
}
```
**Field Descriptions:**
- **id**: Unique execution identifier (number)
- **workflowId**: ID of executed workflow
- **finished**: Whether execution completed (true/false)
- **mode**: How execution was triggered
- **startedAt**: Execution start timestamp (UTC)
- **stoppedAt**: Execution end timestamp (UTC, null if running)
- **retryOf**: Original execution ID if this is a retry
- **retrySuccessId**: Successful retry execution ID (if applicable)
---
### Filtering Examples
**Failed Executions:**
```typescript
// Find all failed executions in production
const failed = await callTool('list_executions', {
instance: 'production',
finished: true,
status: 'error',
limit: 100
});
console.log(`Found ${failed.data.length} failed executions`);
```
**Specific Workflow Executions:**
```typescript
// Get execution history for specific workflow
const workflowRuns = await callTool('list_executions', {
instance: 'production',
workflowId: '123',
limit: 100
});
// Calculate success rate
const successful = workflowRuns.data.filter(e =>
e.finished && !e.error
).length;
const total = workflowRuns.data.filter(e => e.finished).length;
const successRate = (successful / total * 100).toFixed(2);
console.log(`Success rate: ${successRate}%`);
```
**Currently Running Executions:**
```typescript
// Find all currently running executions
const running = await callTool('list_executions', {
instance: 'production',
finished: false
});
console.log(`${running.data.length} executions currently running`);
running.data.forEach(exec => {
const duration = Date.now() - new Date(exec.startedAt).getTime();
console.log(`- Execution ${exec.id}: running for ${duration}ms`);
});
```
---
### Pagination
Same cursor-based pagination as workflows API:
```typescript
async function getAllExecutions(
workflowId: string,
instance?: string
): Promise<ExecutionSummary[]> {
const allExecutions: ExecutionSummary[] = [];
let cursor: string | undefined;
do {
const response = await callTool('list_executions', {
instance,
workflowId,
limit: 100,
cursor
});
const result = JSON.parse(response.content[0].text);
allExecutions.push(...result.data);
cursor = result.nextCursor;
} while (cursor);
return allExecutions;
}
```
---
## get_execution
Get detailed execution data including node outputs, errors, and execution flow.
### Purpose
Retrieve complete execution information for debugging, analysis, and audit purposes. Includes all node data, errors, and execution metadata.
### Use Cases
- Debugging failed workflows
- Analyzing execution performance
- Auditing data flow
- Root cause analysis
- Performance profiling
---
### Request
**MCP Tool Name:** `get_execution`
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| instance | string | No | default | Instance identifier |
| id | number\|string | Yes | - | Execution ID |
| includeData | boolean | No | true | Include execution data (node outputs, errors) |
**TypeScript Interface:**
```typescript
interface GetExecutionParams {
instance?: string;
id: number | string;
includeData?: boolean;
}
```
**JSON-RPC Request:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_execution",
"arguments": {
"instance": "production",
"id": 9876,
"includeData": true
}
}
}
```
---
### Response
**Complete Execution Object:**
**TypeScript Interface:**
```typescript
interface Execution {
id: number;
workflowId: number;
finished: boolean;
mode: ExecutionMode;
startedAt: string;
stoppedAt?: string;
retryOf?: number;
retrySuccessId?: number;
data?: ExecutionData;
}
interface ExecutionData {
resultData: {
runData: {
[nodeName: string]: NodeRun[];
};
lastNodeExecuted: string;
error?: ExecutionError;
};
workflowData: {
id: number;
name: string;
nodes: Node[];
connections: Connections;
};
}
interface NodeRun {
startTime: number; // Unix timestamp (ms)
executionTime: number; // Duration in ms
data: {
main: Array<Array<{
json: Record<string, any>;
binary?: Record<string, BinaryData>;
}>>;
};
error?: {
message: string;
description?: string;
context?: any;
};
}
interface ExecutionError {
message: string;
stack?: string;
context?: any;
}
```
---
### Response Examples
**Successful Execution:**
```json
{
"id": 9876,
"workflowId": 123,
"finished": true,
"mode": "webhook",
"startedAt": "2025-01-15T10:30:00.000Z",
"stoppedAt": "2025-01-15T10:30:02.245Z",
"data": {
"resultData": {
"runData": {
"Webhook": [{
"startTime": 1736936400000,
"executionTime": 12,
"data": {
"main": [[{
"json": {
"headers": {...},
"body": {"order_id": "12345", "amount": 99.99}
}
}]]
}
}],
"Process Order": [{
"startTime": 1736936400012,
"executionTime": 233,
"data": {
"main": [[{
"json": {
"status": "processed",
"order_id": "12345",
"total": 99.99
}
}]]
}
}]
},
"lastNodeExecuted": "Process Order"
},
"workflowData": {
"id": 123,
"name": "Order Processing",
"nodes": [...],
"connections": {...}
}
}
}
```
**Failed Execution:**
```json
{
"id": 9877,
"workflowId": 123,
"finished": true,
"mode": "trigger",
"startedAt": "2025-01-15T11:00:00.000Z",
"stoppedAt": "2025-01-15T11:00:05.123Z",
"data": {
"resultData": {
"runData": {
"Trigger": [{
"startTime": 1736938800000,
"executionTime": 5,
"data": { "main": [[{"json": {...}}]] }
}],
"HTTP Request": [{
"startTime": 1736938800005,
"executionTime": 5118,
"error": {
"message": "ETIMEDOUT: Connection timeout",
"description": "The HTTP request took too long to complete (timeout: 5000ms)"
}
}]
},
"lastNodeExecuted": "HTTP Request",
"error": {
"message": "ETIMEDOUT: Connection timeout",
"stack": "Error: ETIMEDOUT\\n at Timeout.onTimeout (...)"
}
}
}
}
```
---
### Debugging Pattern
**Comprehensive Execution Debugger:**
```typescript
async function debugFailedExecution(
executionId: number,
instance?: string
): Promise<void> {
console.log(`\n=== Debugging Execution ${executionId} ===\n`);
const execution = await callTool('get_execution', {
id: executionId,
instance,
includeData: true
});
const exec = JSON.parse(execution.content[0].text);
// Check execution status
if (!exec.data?.resultData?.error) {
console.log('✅ Execution completed successfully');
return;
}
// Extract error information
const error = exec.data.resultData.error;
const lastNode = exec.data.resultData.lastNodeExecuted;
const runData = exec.data.resultData.runData;
console.log('❌ Execution Failed\n');
console.log(`Workflow: ${exec.data.workflowData.name} (ID: ${exec.workflowId})`);
console.log(`Execution: ${exec.id}`);
console.log(`Started: ${exec.startedAt}`);
console.log(`Stopped: ${exec.stoppedAt}`);
console.log(`Duration: ${
new Date(exec.stoppedAt).getTime() - new Date(exec.startedAt).getTime()
}ms\n`);
console.log(`Last Node Executed: ${lastNode}`);
console.log(`Error Message: ${error.message}\n`);
// Get node-specific error
const nodeRun = runData[lastNode]?.[0];
if (nodeRun?.error) {
console.log('Node Error Details:');
console.log(` Message: ${nodeRun.error.message}`);
if (nodeRun.error.description) {
console.log(` Description: ${nodeRun.error.description}`);
}
if (nodeRun.error.context) {
console.log(` Context: ${JSON.stringify(nodeRun.error.context, null, 2)}`);
}
}
// Analyze execution flow
const executedNodes = Object.keys(runData);
console.log(`\nExecution Flow:`);
executedNodes.forEach((nodeName, i) => {
const runs = runData[nodeName];
const lastRun = runs[runs.length - 1];
const status = lastRun.error ? '❌' : '✅';
console.log(` ${i + 1}. ${status} ${nodeName} (${lastRun.executionTime}ms)`);
});
// Performance analysis
console.log(`\nPerformance:`);
const nodePerformance = executedNodes.map(nodeName => {
const run = runData[nodeName][0];
return { node: nodeName, time: run.executionTime };
}).sort((a, b) => b.time - a.time);
nodePerformance.forEach(({ node, time }) => {
console.log(` ${node}: ${time}ms`);
});
// Suggest retry if recoverable
if (error.message.includes('TIMEOUT') || error.message.includes('ECONNREFUSED')) {
console.log(`\n💡 Suggestion: This appears to be a transient error. Consider retrying.`);
}
}
// Usage
await debugFailedExecution(9877, 'production');
```
---
## retry_execution
Retry a failed execution, creating a new execution as a retry of the original.
### Purpose
Recover from transient failures by retrying failed executions. Creates new execution with `retryOf` reference.
### Use Cases
- Recovering from network timeouts
- Retrying after service outages
- Handling rate limit errors
- Reprocessing after temporary failures
---
### Request
**MCP Tool Name:** `retry_execution`
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instance | string | No | Instance identifier |
| id | number\|string | Yes | Execution ID to retry |
**TypeScript Interface:**
```typescript
interface RetryExecutionParams {
instance?: string;
id: number | string;
}
```
---
### Response
Returns new execution object created as retry:
```typescript
interface RetryExecutionResponse {
id: number; // New execution ID (different from original)
workflowId: number;
retryOf: number; // Original execution ID
mode: 'retry'; // Always 'retry'
finished: boolean;
startedAt: string;
stoppedAt?: string;
data?: ExecutionData;
}
```
---
### Retry Validation
**Pre-Retry Checks:**
```typescript
async function safeRetry(
executionId: number,
instance?: string
): Promise<Execution> {
// Get execution details
const execution = await callTool('get_execution', {
id: executionId,
instance,
includeData: true
});
const exec = JSON.parse(execution.content[0].text);
// Check 1: Execution finished?
if (!exec.finished) {
throw new Error(
`Execution ${executionId} is still running. ` +
`Wait for completion before retrying.`
);
}
// Check 2: Did it actually fail?
if (!exec.data?.resultData?.error) {
throw new Error(
`Execution ${executionId} completed successfully. ` +
`No retry needed.`
);
}
// Check 3: Already retried successfully?
if (exec.retrySuccessId) {
console.warn(
`Warning: Execution ${executionId} was already retried successfully ` +
`(retry execution: ${exec.retrySuccessId})`
);
}
// Safe to retry
console.log(`Retrying execution ${executionId}...`);
const retry = await callTool('retry_execution', {
id: executionId,
instance
});
const result = JSON.parse(retry.content[0].text);
console.log(`Created retry execution: ${result.id}`);
return result;
}
```
---
### Retry Chain Tracking
**Get Complete Retry History:**
```typescript
async function getRetryChain(
executionId: number,
instance?: string
): Promise<Execution[]> {
const chain: Execution[] = [];
let currentId: number | undefined = executionId;
// Walk backwards through retry chain
while (currentId) {
const execution = await callTool('get_execution', {
id: currentId,
instance,
includeData: false // Metadata only for efficiency
});
const exec = JSON.parse(execution.content[0].text);
chain.push(exec);
// Check if this execution was itself a retry
currentId = exec.retryOf;
}
// Reverse to show original first
return chain.reverse();
}
// Usage
const chain = await getRetryChain(10123, 'production');
console.log('Retry Chain:');
chain.forEach((exec, i) => {
const status = exec.finished
? (exec.data?.resultData?.error ? '❌ Failed' : '✅ Success')
: '🔄 Running';
console.log(` ${i + 1}. Execution ${exec.id} - ${status}`);
console.log(` Started: ${exec.startedAt}`);
if (exec.stoppedAt) {
const duration = new Date(exec.stoppedAt).getTime() -
new Date(exec.startedAt).getTime();
console.log(` Duration: ${duration}ms`);
}
});
// Example output:
// Retry Chain:
// 1. Execution 9870 - ❌ Failed
// Started: 2025-01-15T10:00:00Z
// Duration: 5123ms
// 2. Execution 9875 - ❌ Failed
// Started: 2025-01-15T10:05:00Z
// Duration: 4892ms
// 3. Execution 10123 - ✅ Success
// Started: 2025-01-15T10:10:00Z
// Duration: 2145ms
```
---
### Retry Strategies
**1. Simple Retry:**
```typescript
async function simpleRetry(executionId: number, instance?: string) {
const retry = await callTool('retry_execution', {
id: executionId,
instance
});
return JSON.parse(retry.content[0].text);
}
```
**2. Retry with Exponential Backoff:**
```typescript
async function retryWithBackoff(
executionId: number,
instance?: string,
maxAttempts: number = 3
): Promise<Execution> {
let attempt = 1;
let lastError: Error | null = null;
while (attempt <= maxAttempts) {
console.log(`Retry attempt ${attempt}/${maxAttempts}...`);
const retry = await callTool('retry_execution', {
id: executionId,
instance
});
const result = JSON.parse(retry.content[0].text);
// Wait for execution to complete
await waitForCompletion(result.id, instance);
// Check if succeeded
const execution = await callTool('get_execution', {
id: result.id,
instance,
includeData: true
});
const exec = JSON.parse(execution.content[0].text);
if (!exec.data?.resultData?.error) {
console.log(`✅ Retry succeeded on attempt ${attempt}`);
return exec;
}
lastError = new Error(exec.data.resultData.error.message);
console.log(`❌ Retry attempt ${attempt} failed: ${lastError.message}`);
// Exponential backoff: 1s, 2s, 4s, 8s, etc.
if (attempt < maxAttempts) {
const delay = Math.pow(2, attempt - 1) * 1000;
console.log(`Waiting ${delay}ms before next attempt...`);
await new Promise(resolve => setTimeout(resolve, delay));
}
attempt++;
}
throw new Error(
`All ${maxAttempts} retry attempts failed. Last error: ${lastError?.message}`
);
}
async function waitForCompletion(
executionId: number,
instance?: string,
timeout: number = 60000
): Promise<void> {
const startTime = Date.now();
while (Date.now() - startTime < timeout) {
const execution = await callTool('get_execution', {
id: executionId,
instance,
includeData: false
});
const exec = JSON.parse(execution.content[0].text);
if (exec.finished) {
return;
}
// Wait 1 second before checking again
await new Promise(resolve => setTimeout(resolve, 1000));
}
throw new Error(`Execution ${executionId} timeout after ${timeout}ms`);
}
```
---
## delete_execution
Remove execution records permanently. Useful for cleanup and compliance.
### Request
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instance | string | No | Instance identifier |
| id | number\|string | Yes | Execution ID to delete |
### Code Example
```typescript
await callTool('delete_execution', {
instance: 'staging',
id: 9999
});
console.log('Execution deleted successfully');
```
**Warning:** Deletion is permanent and cannot be undone.
---
## Best Practices
### 1. Efficient Execution Listing
```typescript
// ✅ Good: Use server-side filtering
const failed = await callTool('list_executions', {
workflowId: '123',
finished: true,
status: 'error',
limit: 50
});
// ❌ Avoid: Fetch all and filter client-side
const all = await callTool('list_executions', {
workflowId: '123',
limit: 9999 // May timeout!
});
const failed = all.data.filter(e => e.data?.resultData?.error);
```
### 2. Include Data Only When Needed
```typescript
// ✅ Good: Exclude data for listing (faster, smaller)
const executions = await callTool('list_executions', {
workflowId: '123',
includeData: false
});
// ✅ Good: Include data for debugging (slower, detailed)
const execution = await callTool('get_execution', {
id: 9876,
includeData: true
});
// ❌ Avoid: Always including data in list operations
const all = await callTool('list_executions', {
includeData: true, // Wasteful for large lists!
limit: 100
});
```
### 3. Retry with Validation
```typescript
// ✅ Good: Validate before retry
async function retryWithValidation(id: number) {
const exec = await callTool('get_execution', { id });
const execution = JSON.parse(exec.content[0].text);
if (!execution.finished) {
throw new Error('Wait for execution to finish');
}
if (!execution.data?.resultData?.error) {
throw new Error('Execution succeeded, no retry needed');
}
return await callTool('retry_execution', { id });
}
// ❌ Avoid: Blind retry without validation
await callTool('retry_execution', { id: 9876 }); // May fail if still running
```
### 4. Monitor Execution Health
```typescript
async function monitorWorkflowHealth(workflowId: string, instance?: string) {
const executions = await callTool('list_executions', {
instance,
workflowId,
limit: 100
});
const execs = JSON.parse(executions.content[0].text).data;
const finished = execs.filter(e => e.finished);
const successful = finished.filter(e => !e.error);
const successRate = (successful.length / finished.length * 100).toFixed(2);
const avgDuration = finished.reduce((sum, e) => {
const duration = new Date(e.stoppedAt).getTime() -
new Date(e.startedAt).getTime();
return sum + duration;
}, 0) / finished.length;
console.log(`Workflow ${workflowId} Health:`);
console.log(` Success Rate: ${successRate}%`);
console.log(` Avg Duration: ${avgDuration.toFixed(0)}ms`);
console.log(` Total Executions: ${execs.length}`);
console.log(` Running: ${execs.filter(e => !e.finished).length}`);
}
```
---
## Next Steps
- **[Workflows API Reference](workflows-api.md)** - Create and manage workflows
- **[Credentials API Reference](credentials-api.md)** - Schema-driven credential creation
- **[Tags API Reference](tags-api.md)** - Organize workflows with tags
- **[Troubleshooting Guide](../troubleshooting/error-reference.md)** - Common execution errors
---
**Document Version:** 1.0
**Last Updated:** January 2025
**Related Epic:** Epic 4 (Executions Management Tools)
