Overview
The n8n_executions tool with action='delete' permanently removes an execution record and its associated data from n8n.
Permanent Action: Deleted executions cannot be recovered. Ensure you have any necessary data before deletion.
Parameters
Required
Must be set to "delete" for removing execution records.
Execution ID to delete. Must be a valid execution identifier.
Response Fields
Indicates if the execution was successfully deleted.
Confirmation message describing the deletion result.
Examples
{
"action": "delete",
"id": "exec_789xyz"
}
Response Examples
{
"success": true,
"message": "Execution exec_789xyz deleted successfully"
}
Use Cases
Remove execution records from development and testing workflows to keep execution history clean.{
"action": "delete",
"id": "exec_test_123"
}
Delete failed execution records after investigating and resolving the issue.{
"action": "delete",
"id": "exec_error_456"
}
Remove old execution records to free up database storage space.{
"action": "delete",
"id": "exec_2023_old_789"
}
Delete executions containing sensitive data after the retention period.{
"action": "delete",
"id": "exec_sensitive_012"
}
Bulk Deletion Pattern
For deleting multiple executions, combine with n8n_executions list:
Example - Delete Old Failed Executions
// 1. List failed executions
const failedExecs = await n8n_executions({
action: 'list',
status: 'error',
limit: 100
});
// 2. Filter by age (older than 30 days)
const thirtyDaysAgo = Date.now() - (30 * 24 * 60 * 60 * 1000);
const oldExecutions = failedExecs.data.executions.filter(exec => {
return new Date(exec.startedAt).getTime() < thirtyDaysAgo;
});
// 3. Delete each execution
for (const exec of oldExecutions) {
await n8n_executions({
action: 'delete',
id: exec.id
});
}
Example - Delete Test Workflow Executions
// 1. List executions for test workflow
const testExecs = await n8n_executions({
action: 'list',
workflowId: 'test_workflow_123',
limit: 100
});
// 2. Delete all test executions
for (const exec of testExecs.data.executions) {
await n8n_executions({
action: 'delete',
id: exec.id
});
}
Best Practices
- Retrieve execution details with
action='get' before deleting
- Confirm the execution ID matches the intended record
- Export important data if needed for future reference
- Check if the execution is part of a retry chain
Implement Retention Policy
- Define retention periods based on execution status:
- Successful: 7-30 days
- Failed: 30-90 days (for debugging)
- Test: 1-7 days
- Automate cleanup with scheduled workflows
- Keep long-term archives of critical executions
- Don’t fail bulk operations if one deletion fails
- Log deletion results for audit trail
- Implement retry logic for transient failures
- Check for
NOT_FOUND errors (already deleted)
- Check
retryOf and retrySuccessId fields before deleting
- Consider keeping original execution if retries exist
- Delete retry chains in reverse order (latest first)
Common Patterns
Safe Deletion with Verification
// 1. Get execution details
const exec = await n8n_executions({
action: 'get',
id: 'exec_123',
mode: 'preview'
});
// 2. Verify it's the right execution
if (exec.success && exec.data.workflowId === 'expected_workflow') {
// 3. Delete
const result = await n8n_executions({
action: 'delete',
id: 'exec_123'
});
console.log(result.message);
}
Cleanup with Age Filter
// Delete executions older than specified date
async function cleanupOldExecutions(workflowId, daysOld) {
const cutoffDate = Date.now() - (daysOld * 24 * 60 * 60 * 1000);
const executions = await n8n_executions({
action: 'list',
workflowId,
limit: 100
});
for (const exec of executions.data.executions) {
if (new Date(exec.startedAt).getTime() < cutoffDate) {
await n8n_executions({
action: 'delete',
id: exec.id
});
}
}
}
Delete by Status
// Delete all failed executions for a workflow
async function deleteFailedExecutions(workflowId) {
const executions = await n8n_executions({
action: 'list',
workflowId,
status: 'error',
limit: 100
});
for (const exec of executions.data.executions) {
await n8n_executions({
action: 'delete',
id: exec.id
});
}
return executions.data.returned;
}
Error Handling
Execution Not Found
This can occur if:
- Execution was already deleted
- Invalid execution ID provided
- Execution belongs to a different n8n instance
Permission Denied
Ensure your API key has sufficient permissions to delete executions.
Rate Limiting
When deleting many executions:
- Implement delays between deletions
- Batch deletions in smaller groups
- Monitor API response times