# Story 7.3: Executions API Reference Documentation

**Epic:** Epic 7 - API Reference Documentation
**Story Points:** 5
**Priority:** High
**Status:** Ready for Implementation
**Estimated Page Count:** 10-13 pages

---

## User Story

**As a** developer monitoring and managing workflow executions
**I want** complete API reference for execution operations
**So that** I can programmatically track, debug, and retry workflow runs

---

## Story Description

### Current System

With Story 7.2 completed:
- ✅ Workflows API fully documented
- ❌ No executions API reference
- ❌ No execution data structure documentation
- ❌ No retry patterns documented

### Enhancement

Create comprehensive Executions API reference for all 4 execution operations:
- **list_executions** - List execution history with filtering
- **get_execution** - Get detailed execution data
- **delete_execution** - Remove execution records
- **retry_execution** - Retry failed executions

---

## Acceptance Criteria

### AC1: list_executions API Reference

**Document:** `docs/api/executions-api.md#list_executions`

```markdown
# Executions API Reference

Complete API reference for execution management operations (4 methods).

---

## list_executions

List workflow execution history with filtering and pagination.

### Purpose

Retrieve execution records for monitoring, debugging, and analysis.

---

### Request

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instance | string | No | 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 | Include execution data (default: false) |
| limit | number | No | Max executions (1-250, default: 100) |
| cursor | string | No | Pagination cursor |

**TypeScript Interface:**

\`\`\`typescript
interface ListExecutionsParams {
  instance?: string;
  workflowId?: string;
  finished?: boolean;
  status?: 'success' | 'error' | 'waiting';
  includeData?: boolean;
  limit?: number;
  cursor?: string;
}
\`\`\`

---

### Response

\`\`\`typescript
interface ExecutionListResponse {
  data: Array<{
    id: number;
    workflowId: number;
    finished: boolean;
    mode: 'manual' | 'trigger' | 'webhook' | 'retry';
    startedAt: string;
    stoppedAt?: string;
    retryOf?: number;
    retrySuccessId?: number;
  }>;
  nextCursor?: string;
}
\`\`\`

**Example Response:**

\`\`\`json
{
  "data": [
    {
      "id": 9876,
      "workflowId": 123,
      "finished": true,
      "mode": "webhook",
      "startedAt": "2025-01-15T10:30:00Z",
      "stoppedAt": "2025-01-15T10:30:02Z"
    },
    {
      "id": 9875,
      "workflowId": 123,
      "finished": false,
      "mode": "manual",
      "startedAt": "2025-01-15T10:25:00Z"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjEwMH0="
}
\`\`\`

---

### Filtering Examples

**Failed Executions:**

\`\`\`typescript
const failed = await listExecutions({
  instance: 'production',
  finished: true,
  status: 'error',
  limit: 50
});
\`\`\`

**Specific Workflow:**

\`\`\`typescript
const workflowRuns = await listExecutions({
  instance: 'production',
  workflowId: '123',
  limit: 100
});
\`\`\`

**Running Executions:**

\`\`\`typescript
const running = await listExecutions({
  instance: 'production',
  finished: false
});
\`\`\`

---

## get_execution

Get detailed execution data including node outputs and errors.

### Request

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instance | string | No | Instance identifier |
| id | number\|string | Yes | Execution ID |
| includeData | boolean | No | Include execution data (default: true) |

**TypeScript Interface:**

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

---

### Response

**Complete Execution Object:**

\`\`\`typescript
interface Execution {
  id: number;
  workflowId: number;
  finished: boolean;
  mode: 'manual' | 'trigger' | 'webhook' | 'retry';
  startedAt: string;
  stoppedAt?: string;
  retryOf?: number;          // If this is a retry
  retrySuccessId?: number;   // If retry succeeded
  data?: {
    resultData: {
      runData: {
        [nodeName: string]: Array<{
          startTime: number;
          executionTime: number;
          data: {
            main: Array<Array<{
              json: Record<string, any>;
              binary?: Record<string, any>;
            }>>;
          };
          error?: {
            message: string;
            description?: string;
            context?: any;
          };
        }>;
      };
      lastNodeExecuted: string;
      error?: {
        message: string;
        stack?: string;
      };
    };
    workflowData: {
      id: number;
      name: string;
      nodes: Node[];
      connections: Connections;
    };
  };
}
\`\`\`

**Example - Successful Execution:**

\`\`\`json
{
  "id": 9876,
  "workflowId": 123,
  "finished": true,
  "mode": "webhook",
  "startedAt": "2025-01-15T10:30:00Z",
  "stoppedAt": "2025-01-15T10:30:02.245Z",
  "data": {
    "resultData": {
      "runData": {
        "Webhook": [{
          "startTime": 1736936400000,
          "executionTime": 12,
          "data": {
            "main": [[{
              "json": {
                "headers": {...},
                "body": {"order_id": "12345"}
              }
            }]]
          }
        }],
        "Process Order": [{
          "startTime": 1736936400012,
          "executionTime": 233,
          "data": {
            "main": [[{
              "json": {"status": "processed", "order_id": "12345"}
            }]]
          }
        }]
      },
      "lastNodeExecuted": "Process Order"
    }
  }
}
\`\`\`

**Example - Failed Execution:**

\`\`\`json
{
  "id": 9877,
  "workflowId": 123,
  "finished": true,
  "mode": "trigger",
  "startedAt": "2025-01-15T11:00:00Z",
  "stoppedAt": "2025-01-15T11:00:05.123Z",
  "data": {
    "resultData": {
      "runData": {
        "HTTP Request": [{
          "startTime": 1736938800000,
          "executionTime": 5123,
          "error": {
            "message": "ETIMEDOUT: Connection timeout",
            "description": "The request took too long to complete"
          }
        }]
      },
      "lastNodeExecuted": "HTTP Request",
      "error": {
        "message": "ETIMEDOUT: Connection timeout",
        "stack": "Error: ETIMEDOUT\\n    at ..."
      }
    }
  }
}
\`\`\`

---

### Debugging Pattern

\`\`\`typescript
async function debugFailedExecution(
  executionId: number,
  instance?: string
): Promise<void> {
  const execution = await getExecution({
    id: executionId,
    instance,
    includeData: true
  });

  // Check if execution failed
  if (!execution.data?.resultData?.error) {
    console.log('Execution completed successfully');
    return;
  }

  // Extract error information
  const error = execution.data.resultData.error;
  const lastNode = execution.data.resultData.lastNodeExecuted;

  console.log('Execution Failed:');
  console.log('  Last Node:', lastNode);
  console.log('  Error:', error.message);

  // Get node-specific error
  const nodeRun = execution.data.resultData.runData[lastNode]?.[0];
  if (nodeRun?.error) {
    console.log('  Node Error:', nodeRun.error.message);
    console.log('  Description:', nodeRun.error.description);
  }

  // Analyze execution flow
  const executedNodes = Object.keys(execution.data.resultData.runData);
  console.log('  Executed Nodes:', executedNodes.join(' → '));
}
\`\`\`

---

## retry_execution

Retry a failed execution creating a new execution.

### Request

**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
  workflowId: number;
  retryOf: number;         // Original execution ID
  mode: 'retry';
  finished: boolean;
  startedAt: string;
  // ... other execution fields
}
\`\`\`

---

### Retry Validation

**Pre-Retry Checks:**

\`\`\`typescript
async function safeRetry(
  executionId: number,
  instance?: string
): Promise<Execution> {
  // Get execution details
  const execution = await getExecution({ id: executionId, instance });

  // Check 1: Execution finished?
  if (!execution.finished) {
    throw new Error(
      `Execution ${executionId} still running. Wait for completion.`
    );
  }

  // Check 2: Did it actually fail?
  if (!execution.data?.resultData?.error) {
    throw new Error(
      `Execution ${executionId} succeeded. No retry needed.`
    );
  }

  // Check 3: Already retried successfully?
  if (execution.retrySuccessId) {
    console.warn(
      `Execution ${executionId} already retried successfully ` +
      `(retry execution: ${execution.retrySuccessId})`
    );
  }

  // Safe to retry
  return await retryExecution({ id: executionId, instance });
}
\`\`\`

---

### Retry Chain Tracking

\`\`\`typescript
async function getRetryChain(
  executionId: number,
  instance?: string
): Promise<Execution[]> {
  const chain: Execution[] = [];
  let currentId: number | undefined = executionId;

  while (currentId) {
    const execution = await getExecution({ id: currentId, instance });
    chain.push(execution);

    // Check if this execution was itself a retry
    currentId = execution.retryOf;
  }

  return chain.reverse();  // Original first, retries after
}

// Usage
const chain = await getRetryChain(9999);
console.log('Retry chain:');
chain.forEach((exec, i) => {
  console.log(
    `  ${i + 1}. Execution ${exec.id} ` +
    `(${exec.finished ? exec.data?.resultData?.error ? 'Failed' : 'Success' : 'Running'})`
  );
});

// Output:
// Retry chain:
//   1. Execution 9870 (Failed)
//   2. Execution 9875 (Failed)
//   3. Execution 9999 (Success)
\`\`\`

---

## Best Practices

### 1. Efficient Execution Listing

\`\`\`typescript
// ✅ Good: Use filters server-side
const failed = await listExecutions({
  workflowId: '123',
  finished: true,
  status: 'error',
  limit: 50
});

// ❌ Avoid: Fetch all and filter client-side
const all = await listExecutions({ workflowId: '123', limit: 9999 });
const failed = all.data.filter(e => e.data?.resultData?.error);
\`\`\`

### 2. Include Data Only When Needed

\`\`\`typescript
// ✅ Good: Exclude data for listing
const executions = await listExecutions({
  includeData: false  // Faster, smaller response
});

// ✅ Good: Include data for debugging
const execution = await getExecution({
  id: 9876,
  includeData: true  // Full debug information
});

// ❌ Avoid: Always including data
const executions = await listExecutions({
  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 getExecution({ id });

  if (!exec.finished) {
    throw new Error('Wait for execution to finish');
  }

  if (!exec.data?.resultData?.error) {
    throw new Error('Execution succeeded, no retry needed');
  }

  return await retryExecution({ id });
}

// ❌ Avoid: Blind retry
await retryExecution({ id: 9876 });  // May fail if still running
\`\`\`

---

## Next Steps

- [Credentials API Reference](./credentials-api.md)
- [Tags API Reference](./tags-api.md)
- [Debugging Guide](../troubleshooting/debug-mode.md)
```

---

## Dependencies

### Upstream Dependencies
- Story 7.1 (Architecture) - System context
- Story 7.2 (Workflows API) - Related operations
- Epic 4 Story 4.2 (Executions Tools) - Tool specifications

### Downstream Dependencies
- Stories 7.4-7.6 (Other API references)
- Epic 6 (Examples) - Execution debugging patterns

---

## Definition of Done

### Documentation Completeness
- [ ] All 4 execution operations documented
- [ ] Request/response schemas
- [ ] Execution data structure explained
- [ ] Retry patterns documented
- [ ] Code examples provided
- [ ] Error responses documented

---

## Estimation Breakdown

**Story Points:** 5

**Effort Distribution:**
- list_executions: 1.25 SP
- get_execution: 1.5 SP (complex data structure)
- retry_execution: 1 SP
- delete_execution: 0.5 SP
- Code examples: 0.75 SP

**Page Count:** 10-13 pages

**Estimated Duration:** 2-3 days

---

**Status:** Ready for Implementation
**Related Files:**
- `docs/api/executions-api.md`