# Pi-hole

> Control Pi-hole, the network-wide ad blocker: pause blocking for a few minutes and turn it back on, report the day's numbers and top blocked domains, allow or block domains, manage blocklists and update gravity, and search the query log. Start a workflow when blocking is turned off or on, or a domain is blocked.

App · 14 actions. Web page: https://docs.lodol.com/docs/integrations/pihole

## Actions

### Add blocklist

Subscribe Pi-hole to a blocklist (or an allowlist) by its address. Run Update gravity after it to start using its domains.

**Inputs**

- Address (`address`, text, required): The list's address, such as https://example.com/hosts.txt.
- Kind (`list_type`, text): A blocklist blocks its domains; an allowlist never blocks them. One of: `block` (Blocklist), `allow` (Allowlist). Default: `block`.
- Comment (`comment`, text): A note saying what it is, shown in Pi-hole.
- Group (`group`, text): The Pi-hole group it applies to; several separated by commas. Leave blank for the Default group.

**Outputs**

- `added_at` (text): When it was added (ISO 8601, UTC)
- `address` (text): The list's address
- `already_listed` (true/false): True when Pi-hole already had it; its comment and groups were updated
- `comment` (text): Its comment
- `domains` (number): Domains on it at the last gravity update
- `enabled` (true/false): False when it's switched off in Pi-hole
- `groups` (list): The groups it applies to, by name
- `id` (number): The list's ID in Pi-hole
- `invalid_domains` (number): Lines on it that weren't domains
- `list_type` (text): block for a blocklist, allow for an allowlist
- `status` (text): How its last download went: downloaded, unchanged, unavailable, unavailable, using the last copy, or not downloaded yet
- `updated_at` (text): When its domains were last updated (ISO 8601, UTC)

**Example output**

```json
{
  "added_at": "2026-11-07T17:40:00Z",
  "address": "https://example.com/hosts.txt",
  "already_listed": false,
  "comment": "Added by Lodol",
  "domains": 0,
  "enabled": true,
  "groups": [
    "Default"
  ],
  "id": 3,
  "invalid_domains": 0,
  "list_type": "block",
  "status": "not downloaded yet",
  "updated_at": ""
}
```

### Add domain

Put a domain on Pi-hole's deny list to block it, or its allow list to never block it: exactly, with all its subdomains, or as a regular expression. One already there takes the comment and group given.

**Inputs**

- Domain (`domain`, text, required): The domain, such as ads.example.com (a link works too), or a regular expression when Match is Regular expression.
- List (`list_type`, text): Deny to block it, allow to never block it. One of: `allow` (Allow list), `deny` (Deny list). Default: `deny`.
- Match (`match`, text): Exactly this domain, this domain and all its subdomains, or a regular expression. One of: `exact` (Exact domain), `wildcard` (Wildcard (the domain and all its subdomains)), `regex` (Regular expression). Default: `exact`.
- Comment (`comment`, text): A note saying why, shown in Pi-hole.
- Group (`group`, text): The Pi-hole group it applies to; several separated by commas. Leave blank for the Default group.

**Outputs**

- `added_at` (text): When it was added (ISO 8601, UTC)
- `already_listed` (true/false): True when it was already on that list; its comment and groups were updated
- `comment` (text): Its comment
- `domain` (text): The domain as Pi-hole keeps it; a wildcard or regex is the regular expression
- `enabled` (true/false): False when it's switched off in Pi-hole
- `groups` (list): The groups it applies to, by name
- `id` (number): The entry's ID in Pi-hole
- `list_type` (text): Which list it's on: allow or deny
- `match` (text): How it matches: exact or regex (a wildcard is a regex)
- `modified_at` (text): When it last changed (ISO 8601, UTC)

**Example output**

```json
{
  "added_at": "2026-11-07T17:40:00Z",
  "already_listed": false,
  "comment": "Blocked from the help desk",
  "domain": "ads.example.com",
  "enabled": true,
  "groups": [
    "Default"
  ],
  "id": 12,
  "list_type": "deny",
  "match": "exact",
  "modified_at": "2026-11-07T17:40:00Z"
}
```

### Get blocking status

Find out whether Pi-hole is blocking ads, and when a pause ends.

**Inputs**: None.

**Outputs**

- `blocking` (text): Whether Pi-hole is blocking: enabled, disabled, failed or unknown
- `enabled` (true/false): True while Pi-hole is blocking ads
- `switches_at` (text): When blocking switches back by itself (ISO 8601, UTC); empty when it stays
- `timer_seconds` (number): Seconds until blocking switches back by itself; 0 when it stays as it is

**Example output**

```json
{
  "blocking": "disabled",
  "enabled": false,
  "switches_at": "2026-11-07T18:05:00Z",
  "timer_seconds": 300
}
```

### Get summary

Get Pi-hole's numbers for the last 24 hours: queries, how many were blocked and what share, domains, clients, and the size of its blocklists. For a daily report.

**Inputs**: None.

**Outputs**

- `active_clients` (number): Devices that asked something in the last 24 hours
- `blocked_queries` (number): Of those, how many Pi-hole blocked
- `blocking` (text): Whether Pi-hole is blocking: enabled, disabled, failed or unknown
- `cached_queries` (number): Queries answered from Pi-hole's cache
- `domains_on_blocklists` (number): Domains on Pi-hole's blocklists (gravity)
- `forwarded_queries` (number): Queries answered by the upstream DNS server
- `gravity_updated_at` (text): When the blocklists were last updated (ISO 8601, UTC)
- `percent_blocked` (number): The share blocked, in percent, such as 12.5
- `total_clients` (number): Devices Pi-hole has seen
- `total_queries` (number): DNS queries in the last 24 hours
- `unique_domains` (number): Different domains asked for

**Example output**

```json
{
  "active_clients": 14,
  "blocked_queries": 3127,
  "blocking": "enabled",
  "cached_queries": 6091,
  "domains_on_blocklists": 172502,
  "forwarded_queries": 15300,
  "gravity_updated_at": "2026-11-07T03:30:12Z",
  "percent_blocked": 12.8,
  "total_clients": 19,
  "total_queries": 24518,
  "unique_domains": 2214
}
```

### Get top clients

List the devices that asked Pi-hole the most in the last 24 hours, or had the most blocked.

**Inputs**

- Count (`status`, text): Count every query, or only the blocked ones. One of: `any` (Every query), `blocked` (Blocked queries). Default: `any`.
- How many (`count`, number): How many to list. Defaults to 10. From 1 to 100.

**Outputs**

- `blocked_queries` (number): Of those, how many were blocked
- `clients` (list): The devices that asked the most, most first
- `count` (number): How many clients are listed
- `status` (text): Which queries were counted: any or blocked
- `total_queries` (number): All DNS queries Pi-hole has in memory

**Example output**

```json
{
  "blocked_queries": 3127,
  "clients": [
    {
      "ip": "192.168.1.23",
      "name": "living-room-tv.lan",
      "queries": 6120
    },
    {
      "ip": "192.168.1.40",
      "name": "laptop.lan",
      "queries": 3014
    }
  ],
  "count": 2,
  "status": "any",
  "total_queries": 24518
}
```

### Get top domains

List the domains Pi-hole blocked most (or allowed most) in the last 24 hours.

**Inputs**

- Blocked or allowed (`status`, text): Count the blocked queries or the allowed ones. One of: `blocked`, `allowed`. Default: `blocked`.
- How many (`count`, number): How many to list. Defaults to 10. From 1 to 100.

**Outputs**

- `blocked_queries` (number): Of those, how many were blocked
- `count` (number): How many domains are listed
- `domains` (list): The domains asked for most, most first
- `status` (text): Which queries were counted: blocked or allowed
- `total_queries` (number): All DNS queries Pi-hole has in memory

**Example output**

```json
{
  "blocked_queries": 3127,
  "count": 2,
  "domains": [
    {
      "domain": "doubleclick.net",
      "queries": 412
    },
    {
      "domain": "app-measurement.com",
      "queries": 238
    }
  ],
  "status": "blocked",
  "total_queries": 24518
}
```

### List blocklists

List Pi-hole's blocklists and allowlists, with how many domains each has and how its last download went.

**Inputs**

- Kind (`list_type`, text): Only blocklists or only allowlists. One of: `any` (Either), `block` (Blocklist), `allow` (Allowlist). Default: `any`.

**Outputs**

- `count` (number): How many lists there are
- `lists` (list): Every blocklist and allowlist

**Example output**

```json
{
  "count": 1,
  "lists": [
    {
      "added_at": "2026-11-07T17:40:00Z",
      "address": "https://example.com/hosts.txt",
      "comment": "Added by Lodol",
      "domains": 0,
      "enabled": true,
      "groups": [
        "Default"
      ],
      "id": 3,
      "invalid_domains": 0,
      "list_type": "block",
      "status": "not downloaded yet",
      "updated_at": ""
    }
  ]
}
```

### List domains

List the domains on Pi-hole's allow and deny lists, newest first, by list, match, words or group.

**Inputs**

- List (`list_type`, text): Only the allow list or the deny list. One of: `any` (Either), `allow` (Allow list), `deny` (Deny list). Default: `any`.
- Match (`match`, text): Only exact domains, or only regular expressions (wildcards included). One of: `any`, `exact` (Exact domain), `regex` (Regular expression). Default: `any`.
- Search (`search`, text): Only those with these words in the domain or comment.
- Group (`group`, text): Only those in this group.
- How many (`limit`, number): The most to list. Defaults to 100. From 1 to 1000.

**Outputs**

- `count` (number): How many domains are listed
- `domains` (list): The matching entries, newest first
- `total` (number): How many match

**Example output**

```json
{
  "count": 1,
  "domains": [
    {
      "added_at": "2026-11-07T17:40:00Z",
      "comment": "Blocked from the help desk",
      "domain": "ads.example.com",
      "enabled": true,
      "groups": [
        "Default"
      ],
      "id": 12,
      "list_type": "deny",
      "match": "exact",
      "modified_at": "2026-11-07T17:40:00Z"
    }
  ],
  "total": 1
}
```

### Remove blocklist

Unsubscribe Pi-hole from a blocklist or allowlist. Its domains stop counting at the next gravity update. Nothing is removed when it isn't there.

**Inputs**

- Address (`address`, text, required): The list's address, as Pi-hole shows it.
- Kind (`list_type`, text): Which kind to remove when the address is both. Either removes both. One of: `any` (Either), `block` (Blocklist), `allow` (Allowlist). Default: `any`.

**Outputs**

- `address` (text): The list's address
- `lists` (list): The lists removed
- `removed` (number): How many lists were removed; 0 when Pi-hole didn't have it

**Example output**

```json
{
  "address": "https://example.com/hosts.txt",
  "lists": [
    {
      "added_at": "2026-11-07T17:40:00Z",
      "address": "https://example.com/hosts.txt",
      "comment": "Added by Lodol",
      "domains": 0,
      "enabled": true,
      "groups": [
        "Default"
      ],
      "id": 3,
      "invalid_domains": 0,
      "list_type": "block",
      "status": "not downloaded yet",
      "updated_at": ""
    }
  ],
  "removed": 1
}
```

### Remove domain

Take a domain off Pi-hole's allow or deny list, or both. Nothing is removed when it isn't there.

**Inputs**

- Domain (`domain`, text, required): The domain or regular expression, as on the list.
- List (`list_type`, text): Which list to take it off. Either takes it off both. One of: `any` (Either), `allow` (Allow list), `deny` (Deny list). Default: `any`.
- Match (`match`, text): How it was added. Any removes the entry exactly as typed, from either list. One of: `any`, `exact` (Exact domain), `wildcard` (Wildcard (the domain and all its subdomains)), `regex` (Regular expression). Default: `any`.

**Outputs**

- `domain` (text): The domain or pattern looked for
- `entries` (list): The entries removed
- `removed` (number): How many entries were removed; 0 when it wasn't listed

**Example output**

```json
{
  "domain": "ads.example.com",
  "entries": [
    {
      "added_at": "2026-11-07T17:40:00Z",
      "comment": "Blocked from the help desk",
      "domain": "ads.example.com",
      "enabled": true,
      "groups": [
        "Default"
      ],
      "id": 12,
      "list_type": "deny",
      "match": "exact",
      "modified_at": "2026-11-07T17:40:00Z"
    }
  ],
  "removed": 1
}
```

### Search query log

Find recent DNS queries in Pi-hole's log, newest first: for a domain, from a device, blocked only or allowed only, within the last few minutes.

**Inputs**

- Domain (`domain`, text): Only queries for this domain. * matches any characters, such as *.example.com.
- Client (`device`, text): Only queries from this device: its IP address or hostname, as Pi-hole's Query Log shows it. * matches any characters, such as 192.168.1.*.
- Blocked or allowed (`status`, text): Only blocked queries, only allowed ones, or both. One of: `any`, `blocked`, `allowed`. Default: `any`.
- Within the last (minutes) (`minutes`, number): Only queries from the last this many minutes. Leave blank for any time Pi-hole remembers, normally the last 24 hours. From 1 to 10080.
- How many (`limit`, number): The most to list. Defaults to 100. From 1 to 1000.

**Outputs**

- `count` (number): How many queries are listed
- `queries` (list): The matching queries, newest first
- `total` (number): How many in Pi-hole's log match

**Example output**

```json
{
  "count": 1,
  "queries": [
    {
      "blocked": true,
      "client_ip": "192.168.1.23",
      "client_name": "living-room-tv.lan",
      "domain": "ads.example.com",
      "id": 175881,
      "query_type": "A",
      "reason": "on a blocklist",
      "reply": "IP",
      "status": "GRAVITY",
      "time": "2026-11-07T17:58:03Z",
      "upstream": ""
    }
  ],
  "total": 1
}
```

### Turn off blocking

Pause Pi-hole's ad blocking for some minutes, such as for a site that won't load, or until it's turned back on.

**Inputs**

- For how long (minutes) (`minutes`, number): Turn blocking back on by itself after this many minutes, such as 5. Leave blank to keep it off until it's turned back on. From 0.1 to 10080.

**Outputs**

- `blocking` (text): Whether Pi-hole is blocking: enabled, disabled, failed or unknown
- `enabled` (true/false): True while Pi-hole is blocking ads
- `switches_at` (text): When blocking switches back by itself (ISO 8601, UTC); empty when it stays
- `timer_seconds` (number): Seconds until blocking switches back by itself; 0 when it stays as it is

**Example output**

```json
{
  "blocking": "disabled",
  "enabled": false,
  "switches_at": "2026-11-07T18:05:00Z",
  "timer_seconds": 300
}
```

### Turn on blocking

Turn Pi-hole's ad blocking back on, ending any pause.

**Inputs**: None.

**Outputs**

- `blocking` (text): Whether Pi-hole is blocking: enabled, disabled, failed or unknown
- `enabled` (true/false): True while Pi-hole is blocking ads
- `switches_at` (text): When blocking switches back by itself (ISO 8601, UTC); empty when it stays
- `timer_seconds` (number): Seconds until blocking switches back by itself; 0 when it stays as it is

**Example output**

```json
{
  "blocking": "enabled",
  "enabled": true,
  "switches_at": "",
  "timer_seconds": 0
}
```

### Update gravity

Download Pi-hole's blocklists again and rebuild what it blocks, as Tools > Update Gravity does. Says which lists failed to download. Can take a few minutes.

**Inputs**: None.

**Outputs**

- `domains_on_blocklists` (number): Domains on the blocklists now
- `failed_lists` (list): Lists that couldn't be downloaded; Pi-hole keeps their last copy if it has one
- `finished` (true/false): True when the update ran to the end
- `log` (text): Pi-hole's log of the update
- `unique_domains` (number): Of those, how many are different

**Example output**

```json
{
  "domains_on_blocklists": 172507,
  "failed_lists": [],
  "finished": true,
  "log": "[i] Target: https://example.com/hosts.txt\n[\u2713] Status: Retrieval successful\n[i] Number of gravity domains: 172507 (172507 unique domains)\n[\u2713] Done.",
  "unique_domains": 172507
}
```
