Portainer icon

Portainer

Interact with Portainer via API

Actions190

Endpoints → Endpoint List

AI-generated

Overview

This node interacts with the Portainer API to list endpoints (environments) managed by Portainer. It is useful for retrieving detailed information about various endpoints, filtering them based on multiple criteria such as status, type, tags, and provisioning state. Typical use cases include inventory management of environments, monitoring endpoint statuses, or integrating endpoint data into automation workflows.

For example, you could use this node to:

  • Retrieve all provisioned endpoints that match specific tags.
  • List endpoints filtered by their operational status or agent version.
  • Search endpoints by name or group IDs to organize infrastructure views.

Properties

Name Meaning
Additional Fields A collection of optional filters and parameters to refine the endpoint list query:
- Start Start searching from this index (pagination offset).
- Limit Limit the number of results returned.
- Order Sort order of results, ascending or descending.
- Search Text search query to filter endpoints by matching text.
- Group Ids Filter endpoints belonging to these group IDs.
- Status Filter endpoints by their status.
- Types Filter endpoints by their types.
- Tag Ids Filter endpoints having these tag IDs.
- Tags Partial Match If true, returns endpoints having any one of the specified tags; if false, only those having all specified tags.
- Endpoint Ids Return only endpoints with these specific IDs.
- Provisioned If true, return only provisioned endpoints.
- Agent Versions Return endpoints with any of these agent versions.
- Edge Async For edge agents: true to show only async agents, false for standard agents, missing shows both.
- Edge Device Untrusted For edge agents: true to show only untrusted devices, false for trusted ones.
- Edge Check In Passed Seconds For edge agents: show only those checked in within the last given seconds.
- Exclude Snapshots If true, snapshot data will not be retrieved.
- Name Return only endpoints with this exact name.
- Edge Stack Status When edgeStackId exists, filter endpoints by their deployment status in the stack (not environment status).

Output

The node outputs a JSON array containing the list of endpoints matching the specified filters. Each item in the output represents an endpoint object with its properties as returned by the Portainer API. The structure typically includes details like endpoint ID, name, status, type, tags, provisioning info, and other metadata.

If the node supports binary data output (not indicated here), it would represent associated files or snapshots related to endpoints, but in this case, the output is purely JSON data describing endpoints.

Dependencies

  • Requires an API key credential for authenticating with the Portainer API.
  • Needs the base URL of the Portainer instance configured in credentials.
  • Depends on the Portainer REST API being accessible and properly configured.

Troubleshooting

  • Authentication errors: Ensure the API key credential is valid and has sufficient permissions.
  • Empty results: Verify filter parameters are correct and that endpoints exist matching those filters.
  • API connectivity issues: Confirm the Portainer URL is reachable from n8n and no network/firewall blocks exist.
  • Invalid parameter values: Some fields expect JSON arrays or booleans; ensure input formats match expected types.
  • Rate limiting or API errors: Check Portainer API limits and error messages for guidance.

Links and References

Discussion