Pi-hole

App · 14 actions

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.

Actions

ActionWhat it does
Add blocklistSubscribe Pi-hole to a blocklist (or an allowlist) by its address.
Add domainPut 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.
Get blocking statusFind out whether Pi-hole is blocking ads, and when a pause ends.
Get summaryGet 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.
Get top clientsList the devices that asked Pi-hole the most in the last 24 hours, or had the most blocked.
Get top domainsList the domains Pi-hole blocked most (or allowed most) in the last 24 hours.
List blocklistsList Pi-hole's blocklists and allowlists, with how many domains each has and how its last download went.
List domainsList the domains on Pi-hole's allow and deny lists, newest first, by list, match, words or group.
Remove blocklistUnsubscribe Pi-hole from a blocklist or allowlist.
Remove domainTake a domain off Pi-hole's allow or deny list, or both.
Search query logFind 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.
Turn off blockingPause Pi-hole's ad blocking for some minutes, such as for a site that won't load, or until it's turned back on.
Turn on blockingTurn Pi-hole's ad blocking back on, ending any pause.
Update gravityDownload Pi-hole's blocklists again and rebuild what it blocks, as Tools > Update Gravity does.

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

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

Outputs

added_attext
When it was added (ISO 8601, UTC)
addresstext
The list's address
already_listedtrue/false
True when Pi-hole already had it; its comment and groups were updated
commenttext
Its comment
domainsnumber
Domains on it at the last gravity update
enabledtrue/false
False when it's switched off in Pi-hole
groupslist
The groups it applies to, by name
idnumber
The list's ID in Pi-hole
invalid_domainsnumber
Lines on it that weren't domains
list_typetext
block for a blocklist, allow for an allowlist
statustext
How its last download went: downloaded, unchanged, unavailable, unavailable, using the last copy, or not downloaded yet
updated_attext
When its domains were last updated (ISO 8601, UTC)
Example output
{
  "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

DomaindomaintextRequired
The domain, such as ads.example.com (a link works too), or a regular expression when Match is Regular expression.
Listlist_typetext
Deny to block it, allow to never block it.One of: allow (Allow list), deny (Deny list). Default: deny.
Matchmatchtext
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.
Commentcommenttext
A note saying why, shown in Pi-hole.
Groupgrouptext
The Pi-hole group it applies to; several separated by commas. Leave blank for the Default group.

Outputs

added_attext
When it was added (ISO 8601, UTC)
already_listedtrue/false
True when it was already on that list; its comment and groups were updated
commenttext
Its comment
domaintext
The domain as Pi-hole keeps it; a wildcard or regex is the regular expression
enabledtrue/false
False when it's switched off in Pi-hole
groupslist
The groups it applies to, by name
idnumber
The entry's ID in Pi-hole
list_typetext
Which list it's on: allow or deny
matchtext
How it matches: exact or regex (a wildcard is a regex)
modified_attext
When it last changed (ISO 8601, UTC)
Example output
{
  "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

blockingtext
Whether Pi-hole is blocking: enabled, disabled, failed or unknown
enabledtrue/false
True while Pi-hole is blocking ads
switches_attext
When blocking switches back by itself (ISO 8601, UTC); empty when it stays
timer_secondsnumber
Seconds until blocking switches back by itself; 0 when it stays as it is
Example output
{
  "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_clientsnumber
Devices that asked something in the last 24 hours
blocked_queriesnumber
Of those, how many Pi-hole blocked
blockingtext
Whether Pi-hole is blocking: enabled, disabled, failed or unknown
cached_queriesnumber
Queries answered from Pi-hole's cache
domains_on_blocklistsnumber
Domains on Pi-hole's blocklists (gravity)
forwarded_queriesnumber
Queries answered by the upstream DNS server
gravity_updated_attext
When the blocklists were last updated (ISO 8601, UTC)
percent_blockednumber
The share blocked, in percent, such as 12.5
total_clientsnumber
Devices Pi-hole has seen
total_queriesnumber
DNS queries in the last 24 hours
unique_domainsnumber
Different domains asked for
Example output
{
  "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

Countstatustext
Count every query, or only the blocked ones.One of: any (Every query), blocked (Blocked queries). Default: any.
How manycountnumber
How many to list. Defaults to 10.From 1 to 100.

Outputs

blocked_queriesnumber
Of those, how many were blocked
clientslist
The devices that asked the most, most first
countnumber
How many clients are listed
statustext
Which queries were counted: any or blocked
total_queriesnumber
All DNS queries Pi-hole has in memory
Example output
{
  "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 allowedstatustext
Count the blocked queries or the allowed ones.One of: blocked, allowed. Default: blocked.
How manycountnumber
How many to list. Defaults to 10.From 1 to 100.

Outputs

blocked_queriesnumber
Of those, how many were blocked
countnumber
How many domains are listed
domainslist
The domains asked for most, most first
statustext
Which queries were counted: blocked or allowed
total_queriesnumber
All DNS queries Pi-hole has in memory
Example output
{
  "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

Kindlist_typetext
Only blocklists or only allowlists.One of: any (Either), block (Blocklist), allow (Allowlist). Default: any.

Outputs

countnumber
How many lists there are
listslist
Every blocklist and allowlist
Example output
{
  "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

Listlist_typetext
Only the allow list or the deny list.One of: any (Either), allow (Allow list), deny (Deny list). Default: any.
Matchmatchtext
Only exact domains, or only regular expressions (wildcards included).One of: any, exact (Exact domain), regex (Regular expression). Default: any.
Searchsearchtext
Only those with these words in the domain or comment.
Groupgrouptext
Only those in this group.
How manylimitnumber
The most to list. Defaults to 100.From 1 to 1000.

Outputs

countnumber
How many domains are listed
domainslist
The matching entries, newest first
totalnumber
How many match
Example output
{
  "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

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

Outputs

addresstext
The list's address
listslist
The lists removed
removednumber
How many lists were removed; 0 when Pi-hole didn't have it
Example output
{
  "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

DomaindomaintextRequired
The domain or regular expression, as on the list.
Listlist_typetext
Which list to take it off. Either takes it off both.One of: any (Either), allow (Allow list), deny (Deny list). Default: any.
Matchmatchtext
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

domaintext
The domain or pattern looked for
entrieslist
The entries removed
removednumber
How many entries were removed; 0 when it wasn't listed
Example output
{
  "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

Domaindomaintext
Only queries for this domain. * matches any characters, such as *.example.com.
Clientdevicetext
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 allowedstatustext
Only blocked queries, only allowed ones, or both.One of: any, blocked, allowed. Default: any.
Within the last (minutes)minutesnumber
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 manylimitnumber
The most to list. Defaults to 100.From 1 to 1000.

Outputs

countnumber
How many queries are listed
querieslist
The matching queries, newest first
totalnumber
How many in Pi-hole's log match
Example output
{
  "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)minutesnumber
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

blockingtext
Whether Pi-hole is blocking: enabled, disabled, failed or unknown
enabledtrue/false
True while Pi-hole is blocking ads
switches_attext
When blocking switches back by itself (ISO 8601, UTC); empty when it stays
timer_secondsnumber
Seconds until blocking switches back by itself; 0 when it stays as it is
Example output
{
  "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

blockingtext
Whether Pi-hole is blocking: enabled, disabled, failed or unknown
enabledtrue/false
True while Pi-hole is blocking ads
switches_attext
When blocking switches back by itself (ISO 8601, UTC); empty when it stays
timer_secondsnumber
Seconds until blocking switches back by itself; 0 when it stays as it is
Example output
{
  "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_blocklistsnumber
Domains on the blocklists now
failed_listslist
Lists that couldn't be downloaded; Pi-hole keeps their last copy if it has one
finishedtrue/false
True when the update ran to the end
logtext
Pi-hole's log of the update
unique_domainsnumber
Of those, how many are different
Example output
{
  "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
}

On this page