Skip to content

AdGuard Home Module API Explanation

The AdGuard Home module retrieves real-time DNS queries and filtering statistics from target AdGuard Home instances.

API Execution Logic

The backend process parses the active services declared in the configuration file to discover any services with identifiers prefixed by adguard. Each discovered service is dynamically initialized as an independent instance.

For each instance, the module checks for the presence of the required configuration parameters (url, username, and password). The configuration key is transformed into an uppercase string where hyphens are replaced with underscores to look up corresponding environment variables. For example, adguard_pve maps to ADGUARD_PVE_USERNAME and ADGUARD_PVE_PASSWORD.

Request Execution

A fetch request is dispatched to the /control/stats path under the configured base URL. The request is authorized using Basic Authentication, where the credentials are base64-encoded and transmitted via the Authorization header. A timeout signal of 5 seconds is attached to prevent hung requests.

Data Parsing

Upon a successful response, the JSON payload is parsed. The module extracts the following fields:

  • num_dns_queries: Returned as the primary metric.
  • num_blocked_filtering: Returned as the secondary metric.

Caching Strategy

To prevent rate-limiting or network congestion during frequent dashboard updates, the response is cached for 60 seconds (TTL), with a maximum stale tolerance of 300 seconds. If a request fails, cached stale data is returned if available.