# Executions Management Tools
Complete reference for all 4 execution management tools to monitor, analyze, and manage workflow execution history.
---
## Overview
Execution management tools help you track workflow runs, analyze failures, retry executions, and manage execution history.
### Tools Summary
| Tool | Purpose | Filters | Pagination | n8n API Endpoint |
|------|---------|---------|------------|------------------|
| `list_executions` | Get execution history | status, workflowId, includeData | ✅ Cursor | `GET /executions` |
| `get_execution` | Get detailed execution data | includeData | ❌ | `GET /executions/{id}` |
| `delete_execution` | Remove execution record | - | ❌ | `DELETE /executions/{id}` |
| `retry_execution` | Retry failed execution | - | ❌ | `POST /executions/{id}/retry` |
### Execution Lifecycle
```
1. Workflow triggers → Execution starts
2. Nodes execute → Data flows through workflow
3. Execution completes → Success or failure recorded
4. History available → list_executions / get_execution
5. Optional retry → retry_execution (if failed)
6. Optional cleanup → delete_execution
```
---
## list_executions
Retrieve execution history with filtering and pagination support.
### Purpose
Monitor workflow executions, track success rates, identify failures, and analyze execution patterns.
### Input Parameters
```typescript
{
status?: 'success' | 'error' | 'running' | 'waiting';
workflowId?: string; // Filter by specific workflow
includeData?: boolean; // Include full execution data (default: false)
limit?: number; // Results per page (default: 100, max: 250)
cursor?: string; // Pagination cursor
instance?: string; // n8n instance identifier (optional)
}
```
### Output Format
```typescript
{
data: Array<{
id: string; // Execution ID
workflowId: string; // Workflow ID
workflowName?: string; // Workflow name
finished: boolean; // Has execution finished
mode: string; // manual, trigger, webhook, retry
startedAt: string; // ISO 8601 timestamp
stoppedAt?: string; // ISO 8601 timestamp (if finished)
status?: string; // success, error, running
retryOf?: string; // Original execution ID (if retry)
data?: ExecutionData; // Full data (if includeData: true)
}>;
nextCursor?: string; // Pagination cursor
}
```
### Usage Examples
=== "Recent Executions"
**Request:**
```
Show recent workflow executions
```
**What Claude does:**
```typescript
list_executions({ limit: 20 })
```
**Response:**
```
Recent Executions (20 total):
1. Daily Email Report (ID: 456)
- Execution: #789
- Status: ✅ Success
- Started: 2025-12-27 09:00:15
- Duration: 3.2 seconds
- Mode: trigger
2. Data Sync Pipeline (ID: 123)
- Execution: #788
- Status: ❌ Error
- Started: 2025-12-27 08:45:10
- Duration: 1.8 seconds
- Mode: trigger
- Error: Connection timeout
[... 18 more executions ...]
```
=== "Failed Executions Only"
**Request:**
```
Show me all failed executions
```
**What Claude does:**
```typescript
list_executions({ status: 'error' })
```
**Response:**
```
Failed Executions (5 found):
1. Data Sync Pipeline (#788)
- Failed: 2025-12-27 08:45:12
- Error: Database connection timeout
- Workflow ID: 123
2. API Integration (#756)
- Failed: 2025-12-26 14:30:45
- Error: 401 Unauthorized
- Workflow ID: 89
[... 3 more failures ...]
Tip: Use "retry execution [ID]" to retry failed executions
```
=== "Filter by Workflow"
**Request:**
```
Show executions for workflow 15
```
**What Claude does:**
```typescript
list_executions({ workflowId: "15" })
```
=== "Include Full Data"
**Request:**
```
Get last 5 executions with full data
```
**What Claude does:**
```typescript
list_executions({
limit: 5,
includeData: true
})
```
!!! warning "Performance Impact"
Setting `includeData: true` returns large amounts of data. Use only when needed for debugging.
### Execution Status Values
| Status | Description | Icon |
|--------|-------------|------|
| `success` | Execution completed without errors | ✅ |
| `error` | Execution failed with error | ❌ |
| `running` | Currently executing | 🔄 |
| `waiting` | Queued, waiting to execute | ⏳ |
### Execution Modes
| Mode | Description |
|------|-------------|
| `manual` | Manually triggered via n8n UI |
| `trigger` | Triggered by schedule, webhook, etc. |
| `webhook` | Webhook execution |
| `retry` | Retry of failed execution |
| `cli` | CLI execution |
| `error` | Error workflow execution |
---
## get_execution
Retrieve detailed information about a specific execution.
### Purpose
Debug failed executions, analyze node outputs, review execution flow, and validate data transformations.
### Input Parameters
```typescript
{
id: string; // Execution ID (required)
includeData?: boolean; // Include full node data (default: false)
instance?: string; // n8n instance (optional)
}
```
### Output Format
```typescript
{
id: string;
workflowId: string;
workflowName: string;
finished: boolean;
mode: string;
startedAt: string;
stoppedAt?: string;
status: string;
retryOf?: string;
retrySuccessId?: string;
data?: {
resultData: {
runData: {
[nodeName]: Array<{
data: {
main: Array<Array<{ // Node output data
json: Record<string, any>;
binary?: Record<string, any>;
}>>;
};
error?: {
message: string;
stack?: string;
};
startTime: number;
executionTime: number;
}>;
};
};
workflowData: { // Workflow snapshot at execution time
nodes: Array<...>;
connections: Record<...>;
};
};
}
```
### Usage Examples
=== "Basic Execution Details"
**Request:**
```
Show execution 789 details
```
**What Claude does:**
```typescript
get_execution({ id: "789" })
```
**Response:**
```
Execution #789
Workflow: Daily Email Report (ID: 15)
Status: ✅ Success
Mode: trigger
Started: 2025-12-27 09:00:15
Finished: 2025-12-27 09:00:18
Duration: 3.2 seconds
Node Execution:
1. Schedule Trigger - ✅ Success (0.1s)
2. Fetch Data - ✅ Success (1.5s)
3. Transform Data - ✅ Success (0.8s)
4. Send Email - ✅ Success (0.8s)
Total execution time: 3.2 seconds
```
=== "Failed Execution Analysis"
**Request:**
```
Why did execution 788 fail?
```
**What Claude does:**
```typescript
get_execution({
id: "788",
includeData: true
})
```
**Response:**
```
Execution #788 - FAILED ❌
Workflow: Data Sync Pipeline (ID: 123)
Error Details:
- Node: "Connect to Database"
- Error: Connection timeout
- Message: "Failed to connect to database after 30 seconds"
Node Execution Timeline:
1. Schedule Trigger - ✅ Success (0.1s)
2. Connect to Database - ❌ Failed (30.0s)
Error: ETIMEDOUT - Connection timeout
Stack: Error at pg.connect (pg/lib/client.js:45)
Failed at: 2025-12-27 08:45:12
Duration before failure: 30.1 seconds
Suggestion:
- Check database connectivity
- Verify credentials
- Check firewall settings
- Consider increasing timeout
```
=== "With Full Node Data"
**Request:**
```
Show execution 756 with full data
```
**What Claude does:**
```typescript
get_execution({
id: "756",
includeData: true
})
```
**Response includes:**
- Complete node execution data
- Input/output for each node
- Workflow configuration snapshot
- Timing information
### Use Cases
**Debugging:**
- Identify which node failed
- View error messages and stack traces
- Analyze node input/output data
**Performance Analysis:**
- Review execution times per node
- Identify slow operations
- Optimize workflow bottlenecks
**Data Validation:**
- Verify data transformations
- Check API responses
- Validate calculations
---
## delete_execution
Permanently remove an execution record from history.
### Purpose
Clean up execution history, remove failed test executions, or manage storage space.
### Input Parameters
```typescript
{
id: string; // Execution ID (required)
instance?: string; // n8n instance (optional)
}
```
### Output Format
```typescript
{
success: boolean;
message: string;
}
```
### Usage Examples
=== "Delete Single Execution"
**Request:**
```
Delete execution 788
```
**What Claude does:**
```typescript
delete_execution({ id: "788" })
```
**Response:**
```
✅ Successfully deleted execution #788
The execution record has been permanently removed.
```
=== "Clean Up Failed Tests"
**Request:**
```
Delete all failed executions from test workflow
```
**What Claude does:**
```typescript
// Get test workflow ID
const workflows = list_workflows()
const testWorkflow = workflows.data.find(w => w.name.includes("Test"))
// List failed executions for that workflow
const executions = list_executions({
workflowId: testWorkflow.id,
status: 'error'
})
// Delete each failed execution
executions.data.forEach(execution => {
delete_execution({ id: execution.id })
})
```
### Safety Considerations
!!! warning "Irreversible Action"
- **No undo** - Deletion is permanent
- **Data loss** - All execution data and logs removed
- **Audit trail** - Consider keeping records for compliance
!!! tip "Before Deleting"
1. **Review execution** - Ensure you don't need the data
2. **Export if needed** - Save execution data before deletion
3. **Check references** - Verify no retry references exist
### Cleanup Strategies
**Keep:**
- Recent successful executions (last 30 days)
- All failed executions (for analysis)
- Production workflow executions
**Delete:**
- Test workflow executions (after testing complete)
- Old successful executions (>90 days)
- Duplicate retry executions (keep only successful retry)
---
## retry_execution
Retry a failed execution with the same input data.
### Purpose
Automatically retry failed executions without manual workflow re-triggering. Useful for temporary failures (network issues, API rate limits, etc.).
### Input Parameters
```typescript
{
id: string; // Failed execution ID (required)
instance?: string; // n8n instance (optional)
}
```
### Output Format
```typescript
{
success: boolean;
originalExecutionId: string;
newExecutionId: string;
status: string;
message: string;
}
```
### How Retry Works
```
1. Original execution fails → Execution #100 (status: error)
2. Call retry_execution({ id: "100" })
3. New execution created → Execution #101
4. Execution #101 has: retryOf: "100"
5. If #101 succeeds:
- Execution #100 updated with: retrySuccessId: "101"
6. If #101 fails:
- Can retry again, creating #102
```
### Usage Examples
=== "Basic Retry"
**Request:**
```
Retry execution 788
```
**What Claude does:**
```typescript
retry_execution({ id: "788" })
```
**Response:**
```
✅ Successfully queued execution retry!
Original Execution: #788 (failed)
New Execution: #890
Status: Running
Workflow: Data Sync Pipeline (ID: 123)
The workflow will rerun with the same input data.
Monitor with: "Get execution 890 details"
```
=== "Retry After Fix"
**Request:**
```
Execution 788 failed with connection timeout.
I've fixed the network issue. Please retry.
```
**What Claude does:**
```typescript
retry_execution({ id: "788" })
```
**Response:**
```
✅ Retry queued! Execution #890 started.
Previous failure: Connection timeout
Fix applied: Network issue resolved
Running retry now...
Check status with: "Get execution 890"
```
=== "Retry Multiple Failures"
**Request:**
```
Retry all failed executions from last hour
```
**What Claude does:**
```typescript
// Get failed executions from last hour
const oneHourAgo = new Date(Date.now() - 3600000).toISOString()
const executions = list_executions({
status: 'error',
// Filter by time in results
})
// Retry each
executions.data
.filter(e => new Date(e.startedAt) > new Date(oneHourAgo))
.forEach(execution => {
retry_execution({ id: execution.id })
})
```
### When to Retry
**Good Candidates for Retry:**
- ✅ Network timeouts or connection errors
- ✅ API rate limiting (429 errors)
- ✅ Temporary service unavailability (503 errors)
- ✅ Database deadlocks or temporary locks
- ✅ External service outages
**Bad Candidates for Retry:**
- ❌ Invalid credentials (401/403 errors)
- ❌ Malformed data or validation errors
- ❌ Logic errors in workflow
- ❌ Resource not found (404 errors)
- ❌ Permanent failures
### Retry Tracking
**Check Retry Status:**
```
Get execution [original-id]
→ Shows retrySuccessId if retry succeeded
Get execution [retry-id]
→ Shows retryOf linking back to original
```
**Retry Chain:**
```
Execution #100 (failed)
├─ retryOf: null
├─ retrySuccessId: null
└─ Retry → #101 (failed)
├─ retryOf: "100"
├─ retrySuccessId: null
└─ Retry → #102 (success)
├─ retryOf: "101"
└─ Updates #101.retrySuccessId = "102"
```
---
## Common Workflows
### Monitor and Respond to Failures
```
1. Check for failures
→ list_executions({ status: 'error' })
2. Analyze each failure
→ get_execution({ id, includeData: true })
3. Fix underlying issue
→ Update workflow, credentials, etc.
4. Retry failed execution
→ retry_execution({ id })
5. Verify success
→ get_execution({ id: newExecutionId })
```
### Performance Analysis
```
1. Get recent executions with data
→ list_executions({
limit: 100,
includeData: true
})
2. Analyze execution times
→ Review node execution times
→ Identify bottlenecks
3. Optimize workflow
→ update_workflow() with improvements
4. Compare new execution times
→ get_execution() for recent runs
```
### Execution Cleanup
```
1. List old successful executions
→ list_executions({
status: 'success',
// Filter by date
})
2. Delete old records
→ delete_execution({ id })
→ Keep last 30 days
3. Keep all failures
→ Retain for debugging
4. Archive if needed
→ Export data before deletion
```
---
## Best Practices
### Monitoring
!!! tip "Regular Checks"
- Check failed executions daily
- Monitor execution duration trends
- Set up alerts for critical workflows (external monitoring)
### Data Management
!!! tip "Storage Management"
- Use `includeData: false` by default (faster, less data)
- Only use `includeData: true` for debugging
- Clean up old successful executions regularly
- Keep failed executions for analysis
### Retry Strategy
!!! tip "Smart Retries"
- Analyze error before retrying
- Fix root cause before retry
- Don't retry permanent failures
- Track retry success rates
### Performance
!!! tip "Optimization"
- Use pagination for large histories
- Filter by workflow to reduce results
- Monitor slow executions
- Optimize bottleneck nodes
---
## Next Steps
- **[Workflows Management](workflows-management.md)** - Manage workflows
- **[Tags Management](tags-management.md)** - Organize with tags
- **[API Reference](../api/executions-api.md)** - Technical specifications
- **[Troubleshooting](../troubleshooting/error-reference.md)** - Debug execution issues
---
!!! question "Need Help?"
- [Examples](../examples/basic/webhook-workflow.md)
- [GitHub Issues](https://github.com/salacoste/mcp-n8n-workflow-builder/issues)
