Pi-hole icon

Pi-hole

Get information from Pi-hole API

Actions10

Overview

This n8n node interacts with the Pi-hole API to retrieve information about the top clients (devices) making DNS requests through your Pi-hole instance.
Specifically, for the TopClient resource and the Get operation, it fetches a list of clients ranked by the number of requests they have made, in descending order.

Common scenarios:

  • Network administrators want to identify which devices are generating the most DNS traffic.
  • Home users wish to monitor which household devices are most active on their network.
  • Troubleshooting or auditing network usage patterns.

Practical example:
You could use this node in an n8n workflow to automatically generate daily reports of the top 10 devices using your network, or trigger alerts if a single device suddenly spikes in request volume.

Properties

Name Type Meaning
API Url String The base URL of your Pi-hole API endpoint. Defaults to http://localhost/admin/api.php.
Additional Fields Collection Optional fields to further customize the query.
Number Results Number (Within Additional Fields) Limits how many top clients are returned (minimum 1, default 10).

Output

The output is a JSON object containing the list of top clients and their respective request counts.
Typical structure:

{
  "top_clients": {
    "192.168.1.2": 1234,
    "192.168.1.3": 567,
    ...
  }
}
  • The keys are client IP addresses (or hostnames).
  • The values are the number of DNS requests made by each client.
  • The number of results is limited by the "Number Results" property.

Dependencies

  • Pi-hole API: You must have a running Pi-hole instance with its API accessible at the specified API Url.
  • n8n Configuration: No special credentials required unless your Pi-hole API is protected; in that case, configure the appropriate credentials in n8n.

Troubleshooting

Common issues:

  • Incorrect API Url: If the API Url is wrong or unreachable, you will receive connection errors.
  • Insufficient permissions: If the Pi-hole API requires authentication and none is provided, access will be denied.
  • Empty or unexpected output: If there are no recent clients or the filter is too restrictive (e.g., Number Results set too low), the output may be empty.

Error messages and resolutions:

  • "ECONNREFUSED" or "ENOTFOUND": Check that the API Url is correct and the Pi-hole server is running.
  • "401 Unauthorized" or similar: Ensure you have configured any necessary API tokens or credentials in n8n.
  • "Invalid value for 'Number Results'": Make sure the value is a positive integer (minimum 1).

Links and References

Discussion