Executions API

Overview

The Executions API provides endpoints to monitor workflow executions, view their results, retry failed executions, and stop running workflows. Every time a workflow runs, an execution record is created with detailed information about the run.

List Executions

Retrieve a paginated list of workflow executions.

GET /api/v1/executions

Query Parameters

string

Pagination cursor from previous response’s nextCursor

number

default:"100"

Number of executions to return (max: 250)

string

Filter by execution status: success, error, running, waiting, canceled

boolean

default:"false"

Include full execution data in response (significantly increases response size)

string

Filter executions by workflow ID

string

Filter executions by project ID

string

Return executions after this execution ID

Example Request

curl -H "X-N8N-API-KEY: your-api-key" \
  "https://your-n8n-instance.com/api/v1/executions?status=error&limit=20"

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/executions?status=error&limit=20',
  {
    headers: { 'X-N8N-API-KEY': 'your-api-key' }
  }
);

const { data, nextCursor } = await response.json();

import requests

response = requests.get(
    'https://your-n8n-instance.com/api/v1/executions',
    headers={'X-N8N-API-KEY': 'your-api-key'},
    params={'status': 'error', 'limit': 20}
)

executions = response.json()

Response

array

Array of execution summary objects

string

Unique execution identifier

string

ID of the workflow that was executed

string

Name of the executed workflow

string

Execution status: success, error, running, waiting, canceled, crashed

string

Execution mode: manual, trigger, webhook, retry

string

ISO 8601 timestamp when execution started

string | null

ISO 8601 timestamp when execution finished, or null if still running

string | null

Execution ID this is a retry of, or null

string | null

ID of successful retry, or null

string | null

Cursor for next page, or null if no more results

number

Number of currently running executions

Example Response

{
  "data": [
    {
      "id": "exec_123",
      "workflowId": "workflow_abc",
      "workflowName": "Customer Onboarding",
      "status": "error",
      "mode": "trigger",
      "startedAt": "2024-02-19T10:30:00.000Z",
      "stoppedAt": "2024-02-19T10:30:15.234Z",
      "retryOf": null,
      "retrySuccessId": null
    }
  ],
  "count": 1,
  "estimated": false,
  "concurrentExecutionsCount": 3,
  "nextCursor": "eyJsYXN0SWQiOiJleGVjXzEyMyIsImxpbWl0IjoyMH0"
}

Get Execution

Retrieve detailed information about a specific execution.

GET /api/v1/executions/:id

Path Parameters

string

required

The execution ID

Query Parameters

boolean

default:"false"

Include full execution data and node outputs

Example Request

curl -H "X-N8N-API-KEY: your-api-key" \
  "https://your-n8n-instance.com/api/v1/executions/exec_123?includeData=true"

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/executions/exec_123?includeData=true',
  {
    headers: { 'X-N8N-API-KEY': 'your-api-key' }
  }
);

const execution = await response.json();
console.log('Execution status:', execution.status);
console.log('Node outputs:', execution.data?.resultData);

Response

string

Execution ID

string

Workflow ID

string

Execution status

string

Execution mode

string

Start timestamp

string | null

Stop timestamp

object

Execution data (only when includeData=true)

object

Node execution results and outputs

object

Metadata about the execution

Example Response

{
  "id": "exec_123",
  "workflowId": "workflow_abc",
  "status": "success",
  "mode": "manual",
  "startedAt": "2024-02-19T10:30:00.000Z",
  "stoppedAt": "2024-02-19T10:30:05.123Z",
  "data": {
    "resultData": {
      "runData": {
        "Webhook": [
          {
            "startTime": 1708338600000,
            "executionTime": 12,
            "data": {
              "main": [
                [
                  {
                    "json": {
                      "email": "customer@example.com",
                      "name": "John Doe"
                    }
                  }
                ]
              ]
            }
          }
        ]
      }
    }
  }
}

Setting includeData=true returns the full execution data including all node inputs and outputs. This can be a very large response for complex workflows.

Stop Execution

Stop a currently running execution.

POST /api/v1/executions/:id/stop

Path Parameters

string

required

The execution ID to stop

Example Request

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  https://your-n8n-instance.com/api/v1/executions/exec_123/stop

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/executions/exec_123/stop',
  {
    method: 'POST',
    headers: { 'X-N8N-API-KEY': 'your-api-key' }
  }
);

const result = await response.json();

Response

Returns the stopped execution object with status: "canceled".

{
  "id": "exec_123",
  "status": "canceled",
  "stoppedAt": "2024-02-19T10:31:00.000Z"
}

Stop Many Executions

Stop multiple running executions based on filters.

POST /api/v1/executions/stopMany

Request Body

object

required

Filter criteria for executions to stop

string

Filter by workflow ID, or “all” for all workflows

string[]

required

Array of statuses to stop: ["running", "waiting", "queued"]

string

ISO 8601 timestamp - only stop executions started after this time

string

ISO 8601 timestamp - only stop executions started before this time

Example Request

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "workflowId": "workflow_abc",
      "status": ["running", "waiting"]
    }
  }' \
  https://your-n8n-instance.com/api/v1/executions/stopMany

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/executions/stopMany',
  {
    method: 'POST',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      filter: {
        workflowId: 'workflow_abc',
        status: ['running', 'waiting']
      }
    })
  }
);

const result = await response.json();
console.log(`Stopped ${result.stopped} executions`);

Response

{
  "stopped": 5
}

This operation stops all matching executions. Use filters carefully to avoid stopping unintended executions.

Retry Execution

Retry a failed or canceled execution.

POST /api/v1/executions/:id/retry

Path Parameters

string

required

The execution ID to retry

Request Body

boolean

default:"false"

Whether to load the latest workflow version (true) or use the original version (false)

Example Request

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"loadWorkflow": false}' \
  https://your-n8n-instance.com/api/v1/executions/exec_123/retry

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/executions/exec_123/retry',
  {
    method: 'POST',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ loadWorkflow: false })
  }
);

const retriedExecution = await response.json();
console.log('New execution ID:', retriedExecution.id);

Response

Returns a new execution object with the retry information:

{
  "id": "exec_456",
  "workflowId": "workflow_abc",
  "status": "running",
  "mode": "retry",
  "retryOf": "exec_123",
  "startedAt": "2024-02-19T10:35:00.000Z"
}

Only failed, canceled, or crashed executions can be retried
The retry creates a new execution linked to the original via retryOf
Setting loadWorkflow: true uses the current workflow version, which may differ from the original execution

Delete Execution

Permanently delete an execution and its data.

POST /api/v1/executions/delete

Request Body

string[]

required

Array of execution IDs to delete

Example Request

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["exec_123", "exec_456", "exec_789"]
  }' \
  https://your-n8n-instance.com/api/v1/executions/delete

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/executions/delete',
  {
    method: 'POST',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ids: ['exec_123', 'exec_456', 'exec_789']
    })
  }
);

const result = await response.json();

Response

{
  "success": true
}

Deleting executions permanently removes all execution data including logs and outputs. This cannot be undone.

Update Execution

Update execution metadata such as annotations.

PATCH /api/v1/executions/:id

Path Parameters

string

required

The execution ID to update

Request Body

object

Annotation data to attach to the execution

string[]

Array of tag IDs to assign

string

User vote: “up” or “down”

Example Request

curl -X PATCH \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "annotation": {
      "tags": ["tag_production", "tag_urgent"],
      "vote": "up"
    }
  }' \
  https://your-n8n-instance.com/api/v1/executions/exec_123

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/executions/exec_123',
  {
    method: 'PATCH',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      annotation: {
        tags: ['tag_production', 'tag_urgent'],
        vote: 'up'
      }
    })
  }
);

const updated = await response.json();

Response

Returns the updated execution object.

Execution Status Values

Executions can have the following status values:

status

Execution completed successfully without errors

status

Execution failed with an error in one or more nodes

status

Execution is currently in progress

status

Execution is waiting for an external event or condition

status

Execution was manually stopped by a user

status

Execution crashed unexpectedly (system error)

status

Execution is queued and waiting to start

Common Patterns

Monitor Workflow Execution

async function waitForExecution(executionId) {
  const maxAttempts = 60;
  const pollInterval = 2000; // 2 seconds
  
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://your-n8n-instance.com/api/v1/executions/${executionId}`,
      { headers: { 'X-N8N-API-KEY': 'your-api-key' } }
    );
    
    const execution = await response.json();
    
    if (['success', 'error', 'canceled', 'crashed'].includes(execution.status)) {
      return execution;
    }
    
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }
  
  throw new Error('Execution timeout');
}

const result = await waitForExecution('exec_123');
console.log('Execution finished with status:', result.status);

Clean Up Old Executions

const thirtyDaysAgo = new Date();
thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);

// Fetch old executions
const response = await fetch(
  'https://your-n8n-instance.com/api/v1/executions?limit=100',
  { headers: { 'X-N8N-API-KEY': 'your-api-key' } }
);

const { data } = await response.json();

// Filter executions older than 30 days
const oldExecutionIds = data
  .filter(exec => new Date(exec.startedAt) < thirtyDaysAgo)
  .map(exec => exec.id);

if (oldExecutionIds.length > 0) {
  // Delete in batches
  await fetch(
    'https://your-n8n-instance.com/api/v1/executions/delete',
    {
      method: 'POST',
      headers: {
        'X-N8N-API-KEY': 'your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ ids: oldExecutionIds })
    }
  );
  
  console.log(`Deleted ${oldExecutionIds.length} old executions`);
}

Retry All Failed Executions

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/executions?status=error&limit=50',
  { headers: { 'X-N8N-API-KEY': 'your-api-key' } }
);

const { data } = await response.json();

for (const execution of data) {
  try {
    await fetch(
      `https://your-n8n-instance.com/api/v1/executions/${execution.id}/retry`,
      {
        method: 'POST',
        headers: {
          'X-N8N-API-KEY': 'your-api-key',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ loadWorkflow: true })
      }
    );
    console.log(`Retried execution ${execution.id}`);
  } catch (error) {
    console.error(`Failed to retry ${execution.id}:`, error);
  }
}

Error Responses

404 Not Found

{
  "message": "Execution not found"
}

409 Conflict

{
  "message": "Cannot retry a running or waiting execution"
}

400 Bad Request

{
  "message": "Cannot delete a running execution"
}

Next Steps

Workflows API

Manage workflows programmatically

Credentials API

Manage workflow credentials

Execution Data

Learn about execution data structure

Error Handling

Handle execution errors

​Overview

​List Executions

​Query Parameters

​Example Request

​Response

​Get Execution

​Path Parameters

​Query Parameters

​Example Request

​Response

​Stop Execution

​Path Parameters

​Example Request

​Response

​Stop Many Executions

​Request Body

​Example Request

​Response

​Retry Execution

​Path Parameters

​Request Body

​Example Request

​Response

​Delete Execution

​Request Body

​Example Request

​Response

​Update Execution

​Path Parameters

​Request Body

​Example Request

​Response

​Execution Status Values

​Common Patterns

​Monitor Workflow Execution

​Clean Up Old Executions

​Retry All Failed Executions

​Error Responses

​404 Not Found

​409 Conflict

​400 Bad Request

​Next Steps

Workflows API

Credentials API

Execution Data

Error Handling

Overview

List Executions

Query Parameters

Example Request

Response

Get Execution

Path Parameters

Query Parameters

Example Request

Response

Stop Execution

Path Parameters

Example Request

Response

Stop Many Executions

Request Body

Example Request

Response

Retry Execution

Path Parameters

Request Body

Example Request

Response

Delete Execution

Request Body

Example Request

Response

Update Execution

Path Parameters

Request Body

Example Request

Response

Execution Status Values

Common Patterns

Monitor Workflow Execution

Clean Up Old Executions

Retry All Failed Executions

Error Responses

404 Not Found

409 Conflict

400 Bad Request

Next Steps