Executions API Reference¶

interface ListExecutionsParams {
  instance?: string;
  workflowId?: string;
  finished?: boolean;
  status?: 'success' | 'error' | 'waiting';
  includeData?: boolean;
  limit?: number;   // Range: 1-250
  cursor?: string;
}

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

// 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`);

// 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}%`);

// 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`);
});

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;
}

interface GetExecutionParams {
  instance?: string;
  id: number | string;
  includeData?: boolean;
}

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;
}

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');

interface RetryExecutionParams {
  instance?: string;
  id: number | string;
}

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;
}

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;
}

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

async function simpleRetry(executionId: number, instance?: string) {
  const retry = await callTool('retry_execution', {
    id: executionId,
    instance
  });

  return JSON.parse(retry.content[0].text);
}

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`);
}

await callTool('delete_execution', {
  instance: 'staging',
  id: 9999
});

console.log('Execution deleted successfully');

// ✅ 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);

// ✅ 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
});

// ✅ 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

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}`);
}