Overview Retrieve a list of workflows from your n8n instance with filtering, sorting, and pagination support. Returns minimal metadata for optimal performance.
Endpoint Request Parameters Number of workflows to return (1-100) Example: 20
Pagination cursor from previous response Used to fetch the next page of results. See Pagination section. Filter by active status
true - Only active workflowsfalse - Only inactive workflowsOmit to return both
Filter by tags (exact match) Example: ["production", "crm"]Returns workflows that have ALL specified tags (AND logic)
Filter by project ID (n8n Enterprise feature) Example: "proj_abc123"
Exclude pinned test data from response Reduces response size. Set to false to include pinned data.
Response Workflow list with metadata Array of workflow objects Workflow unique identifier
Archive status (if supported)
ISO 8601 creation timestamp
ISO 8601 last update timestamp
Number of nodes in workflow
Number of workflows in this response
Cursor for next page (if more results available)
Whether more results are available
The API uses cursor-based pagination for efficient navigation through large workflow lists.
How It Works
First Request: Omit cursor parameterCheck Response: Look for nextCursor in responseNext Page: Pass nextCursor as cursor parameterRepeat: Until hasMore is false
Example Flow
Initial Request
Response includes nextCursor: "abc123"
Next Page
{ "limit" : 20 , "cursor" : "abc123" }
Response includes nextCursor: "def456"
Continue
Repeat until hasMore: false
Cursors are opaque strings. Do not parse or modify them.
Error Codes Cause: Limit outside valid range (1-100)Resolution: Use a value between 1 and 100
Cause: Cursor is invalid or expiredResolution: Start from beginning (omit cursor)
Cause: n8n API not configured or unreachableResolution: Verify configuration with n8n_health_check
Examples List All Workflows (First Page)
List Active Workflows
Filter by Tags
Pagination - Next Page
Filter by Project (Enterprise)
curl -X GET "https://n8n.example.com/api/v1/workflows?limit=20" \ -H "X-N8N-API-KEY: your-api-key"
Response Examples First Page Response
Last Page Response
No Results
{ "success" : true , "data" : { "workflows" : [ { "id" : "wf_abc123" , "name" : "Customer Onboarding" , "active" : true , "isArchived" : false , "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-03-05T14:22:00.000Z" , "tags" : [ "production" , "crm" ], "nodeCount" : 8 }, { "id" : "wf_def456" , "name" : "Daily Data Sync" , "active" : true , "isArchived" : false , "createdAt" : "2024-02-01T09:15:00.000Z" , "updatedAt" : "2024-03-04T16:45:00.000Z" , "tags" : [ "production" , "automation" ], "nodeCount" : 5 } ], "returned" : 2 , "nextCursor" : "xyz789" , "hasMore" : true , "_note" : "More workflows available. Use cursor to get next page." } }
Common Use Cases Workflow Discovery
Monitoring
Bulk Operations
Search by Name
Find all workflows for a specific purpose: # List production workflows n8n_list_workflows( {tags: [ "production" ], active: true}) # List inactive workflows (candidates for cleanup) n8n_list_workflows( {active: false } )
Monitor workflow inventory: const response = await n8n_list_workflows ({ limit: 100 }) console . log ( `Total workflows: ${ response . data . returned } ` ) console . log ( `Active: ${ response . data . workflows . filter ( w => w . active ). length } ` ) console . log ( `Inactive: ${ response . data . workflows . filter ( w => ! w . active ). length } ` )
Perform operations on multiple workflows: // Archive all workflows tagged "deprecated" const workflows = await n8n_list_workflows ({ tags: [ "deprecated" ]}) for ( const workflow of workflows . data . workflows ) { await n8n_update_partial_workflow ({ id: workflow . id , operations: [ { type: "deactivateWorkflow" }, { type: "addTag" , tag: "archived" } ] }) }
Client-side filtering by name: const response = await n8n_list_workflows ({ limit: 100 }) const matching = response . data . workflows . filter ( w => w . name . toLowerCase (). includes ( "webhook" ) )
n8n API doesn’t support server-side name search. Fetch all workflows and filter client-side.
Filtering Best Practices Optimal Filtering Strategy:
Start broad: Fetch workflows with minimal filtersUse tags: Organize workflows with meaningful tags for efficient filteringPaginate properly: Use cursors, don’t skip pagesCache results: Store workflow lists locally for dashboardsCombine filters: Use active + tags for precise queries Example: Production Active Workflows { "active" : true , "tags" : [ "production" ], "limit" : 50 }
Returns only workflows that are:
Currently active
Tagged with “production”
Limited to first 50 results
Tag Organization
Environment
productionstagingdevelopmenttesting
Function
data-syncnotificationprocessingmonitoring
System
crmecommerceanalyticsintegrations
Status
active-productiondeprecatedarchivedto-delete Optimize Large Lists:
Use reasonable limit values (20-50 for UI, 100 for batch)
Don’t fetch all workflows unnecessarily
Cache workflow lists with short TTL (5-10 minutes)
Use excludePinnedData: true (default) to reduce response size
Filter server-side with tags instead of fetching all
Workflow List Management Export Workflow List // Export all workflows for backup/audit const allWorkflows = [] let cursor = null do { const response = await n8n_list_workflows ({ limit: 100 , cursor , excludePinnedData: true }) allWorkflows . push ( ... response . data . workflows ) cursor = response . data . nextCursor } while ( cursor ) console . log ( `Exported ${ allWorkflows . length } workflows` )
Workflow Inventory Report const response = await n8n_list_workflows ({ limit: 100 }) const workflows = response . data . workflows const report = { total: workflows . length , active: workflows . filter ( w => w . active ). length , inactive: workflows . filter ( w => ! w . active ). length , byTag: {}, avgNodeCount: workflows . reduce (( sum , w ) => sum + w . nodeCount , 0 ) / workflows . length , lastUpdated: workflows . sort (( a , b ) => new Date ( b . updatedAt ) - new Date ( a . updatedAt ) )[ 0 ] } // Count by tag workflows . forEach ( w => { w . tags . forEach ( tag => { report . byTag [ tag ] = ( report . byTag [ tag ] || 0 ) + 1 }) }) console . log ( report )
Conceived by Romuald Członkowski - www.aiadvisors.pl/en