Skip to main content
GET
/
api
/
executions
List Executions
curl --request GET \
  --url https://api.example.com/api/executions
{
  "success": true,
  "data": {
    "executions": [
      {
        "id": "<string>",
        "workflowId": "<string>",
        "workflowName": "<string>",
        "status": "<string>",
        "mode": "<string>",
        "startedAt": "<string>",
        "stoppedAt": "<string>",
        "finished": true,
        "retryOf": "<string>",
        "retrySuccessId": "<string>",
        "data": {}
      }
    ],
    "returned": 123,
    "nextCursor": "<string>",
    "hasMore": true
  }
}

​
Overview

The n8n_executions tool with action='list' retrieves execution history across workflows. Use filters to narrow results by workflow, status, or project.
Execution data is not included by default to reduce response size. Set includeData: true to retrieve full execution data.

​
Parameters

​
Required

​
action
string
required
Must be set to "list" for listing executions.

​
Pagination

​
limit
number
default:"100"
Number of executions to return per request.
  • Minimum: 1
  • Maximum: 100
  • Default: 100
​
cursor
string
Pagination cursor from the previous response’s nextCursor field. Use for retrieving subsequent pages.

​
Filters

​
workflowId
string
Filter executions by workflow ID. Returns only executions for the specified workflow.
​
status
enum
Filter by execution status.
​
projectId
string
Filter by project ID. Enterprise feature for multi-project deployments.

​
Data Options

​
includeData
boolean
default:"false"
Include full execution data in the response.
Setting this to true significantly increases response size. Use only when execution data is needed.

​
Response Fields

​
success
boolean
required
Indicates if the request was successful.
​
data
object
required
Container for the execution list and pagination metadata.

​
Examples

{
  "action": "list",
  "limit": 20
}

​
Response Examples

{
  "success": true,
  "data": {
    "executions": [
      {
        "id": "exec_789xyz",
        "workflowId": "abc123",
        "workflowName": "Customer Onboarding",
        "status": "success",
        "mode": "webhook",
        "startedAt": "2024-01-15T10:30:00.000Z",
        "stoppedAt": "2024-01-15T10:30:05.234Z",
        "finished": true,
        "retryOf": null,
        "retrySuccessId": null
      },
      {
        "id": "exec_456abc",
        "workflowId": "def456",
        "workflowName": "Email Notification",
        "status": "error",
        "mode": "trigger",
        "startedAt": "2024-01-15T10:25:00.000Z",
        "stoppedAt": "2024-01-15T10:25:03.120Z",
        "finished": true,
        "retryOf": null,
        "retrySuccessId": null
      }
    ],
    "returned": 2,
    "nextCursor": "eyJpZCI6ImV4ZWNfNDU2YWJjIn0=",
    "hasMore": true,
    "_note": "More executions available. Use cursor to get next page."
  }
}

​
Pagination Pattern

For large execution sets, use cursor-based pagination:
Pagination Example
// First request
const page1 = await n8n_executions({
  action: 'list',
  limit: 50
});

// Check for more results
if (page1.data.hasMore) {
  // Request next page
  const page2 = await n8n_executions({
    action: 'list',
    limit: 50,
    cursor: page1.data.nextCursor
  });
}

​
Execution Modes

Workflow was executed manually via the n8n UI “Execute Workflow” button or API call.
Workflow was triggered automatically by a trigger node (schedule, webhook, etc.).
Workflow was triggered via webhook endpoint (production or test mode).
Workflow execution is a retry of a failed execution.
Workflow was triggered by another workflow or internal n8n process.

​
Best Practices

  • Avoid includeData: true unless execution data is required
  • Use appropriate limit values (20-50 for UI display, 100 for batch processing)
  • Filter by workflowId when possible to reduce result set
  • Store nextCursor for subsequent requests
  • Check hasMore before requesting next page
  • Break pagination loop when reaching desired result count
  • Use status: 'error' to quickly identify failed executions
  • Combine with workflowId for workflow-specific monitoring
  • Check recent executions first (most recent returned first)
  • Calculate execution duration: stoppedAt - startedAt
  • Track status distribution for reliability metrics
  • Monitor retryOf and retrySuccessId for retry patterns

​
Common Use Cases

​
Monitor Recent Errors

{
  "action": "list",
  "status": "error",
  "limit": 20
}

​
Workflow Health Check

{
  "action": "list",
  "workflowId": "abc123",
  "limit": 100
}

​
Audit Trail

{
  "action": "list",
  "includeData": true,
  "limit": 50
}

Build docs developers (and LLMs) love

Get started for freeTalk to us