---
title: "HitKeep Traffic Exclusions and IP Filtering | HitKeep"
description: "Exclude traffic by network, country, user agent, or path at instance, team, and site scope before it reaches HitKeep analytics storage."
canonical: "https://hitkeep.com/guides/tracking/ip-exclusions/"
---

# HitKeep Traffic Exclusions and IP Filtering

Your own visits, synthetic checks, known bots, internal routes, or traffic from countries you do not serve can skew analytics. HitKeep drops matching traffic before queue publication or direct storage. A rule can apply to one site, every site currently owned by a team, or every site in the instance.

Traffic exclusions are additive and forward-only. There are no allow overrides: HitKeep evaluates instance rules, then the site’s current team rules, then site rules, and drops the record when any rule matches. Existing analytics rows are not changed when a rule is created or deleted.

Trusted proxies required for accuracy

IP/CIDR exclusions match against the **real client IP** as resolved by HitKeep. Country exclusions use trusted CDN/proxy country headers only when the request came through configured trusted proxies, then fall back to HitKeep’s IP metadata lookup. If you run behind a reverse proxy (Caddy, Traefik, nginx, or a cloud load balancer), configure the `-trusted-proxies` flag so both rule types evaluate the real visitor context.

See [Trusted Proxies](https://hitkeep.com/guides/installation/trusted-proxies/) for setup instructions.

## Rule types and matching

Each rule uses exactly one value:

| Rule type | Matching behavior |
| --- | --- |
| IP/CIDR | Matches the resolved client IP against one address or network. Plain addresses are normalized to /32 for IPv4 or /128 for IPv6. |
| Country | Matches an ISO 3166-1 alpha-2 country code after trusted-header or IP-metadata resolution. |
| User agent | Case-insensitive substring match. HealthCheck also matches acme-healthcheck/2.0. |
| Path | Case-sensitive segment-boundary match after removing query strings and fragments and cleaning duplicate slashes, trailing slashes, and dot segments. /admin matches /admin and /admin/users, but not /administrator. / matches every path. |

User-agent and path values are used only during filtering. Adding these rules does not add persisted visitor fields.

## Per-site exclusions

Use a site rule when traffic should be excluded for one site only. Site owners and site admins can manage these rules for their assigned sites. Instance admins also have the narrow site-exclusion override, which does not grant broader site data mutation rights.

In the dashboard, open **Site settings → Filtering**, then choose a rule type and add its value. The table also shows inherited instance and current-team rules with scope labels. Inherited rows are read-only at the site scope.

API reference:

- [List site exclusion rules](https://hitkeep.com/api/#tag/sites/GET/api/sites/%7Bid%7D/exclusions)
- [Create a site exclusion rule](https://hitkeep.com/api/#tag/sites/POST/api/sites/%7Bid%7D/exclusions)
- [Delete a site exclusion rule](https://hitkeep.com/api/#tag/sites/DELETE/api/sites/%7Bid%7D/exclusions/%7BruleID%7D)

By default, `GET /api/sites/{id}/exclusions` returns only rules owned by the site. Add `?effective=true` to receive rules in instance → team → site order, newest-first within each scope. Inherited rows set `inherited: true` and omit cross-scope creator IDs.

## Team exclusions

Team owners and admins with `team.manage_settings` can manage rules at **Administration → Team → Traffic Filters**. A team rule applies to every site currently owned by that team.

![HitKeep team traffic filters showing an inherited instance user-agent rule and team-owned path and CIDR rules](https://hitkeep.com/_astro/team-traffic-exclusions-inherited.Brr3hv1v_ZSnLGJ.webp)

Effective reads identify each rule’s scope. Inherited instance rules are visible but cannot be edited or deleted from the team.

API reference:

- [List team exclusion rules](https://hitkeep.com/api/#tag/teams/GET/api/user/teams/%7Bid%7D/exclusions)
- [Create a team exclusion rule](https://hitkeep.com/api/#tag/teams/POST/api/user/teams/%7Bid%7D/exclusions)
- [Delete a team exclusion rule](https://hitkeep.com/api/#tag/teams/DELETE/api/user/teams/%7Bid%7D/exclusions/%7BruleID%7D)

By default, the team list returns only team-owned rules. `?effective=true` prepends inherited instance rules. A team route cannot delete an inherited instance rule.

Site transfer changes which team rules apply immediately. Site-owned rules remain attached to the site. Deleting a site removes its site rules; purging a team removes its team rules.

## Instance-wide exclusions

Instance administrators with `instance.manage_site_exclusions` can add global rules that apply across all sites. Use them for known datacenter ranges, monitoring user agents, internal paths, an office subnet, or countries that should be excluded everywhere.

![HitKeep global traffic filters showing CIDR, country, user-agent, and path exclusion rules](https://hitkeep.com/_astro/global_filters.DsN5WBeZ_19wfQT.webp)

Global filters can mix CIDR, country, user-agent, and path rules in the same instance-wide table.

API reference:

- [List global exclusion rules](https://hitkeep.com/api/#tag/admin/GET/api/admin/exclusions)
- [Create a global exclusion rule](https://hitkeep.com/api/#tag/admin/POST/api/admin/exclusions)
- [Delete a global exclusion rule](https://hitkeep.com/api/#tag/admin/DELETE/api/admin/exclusions/%7BruleID%7D)

For generated-client compatibility, the API schema keeps the `IPExclusion` and `IPExclusionCreateRequest` names. Legacy creation payloads that omit `type` and provide `cidr` continue to create CIDR rules.

## Ingest coverage and response behavior

Filtering runs before NSQ publication or direct storage for:

- browser pageviews and custom events;
- opt-in browser Web Vitals;
- trusted server-side pageviews and events;
- AI-fetch records;
- dynamic QR opens.

Browser events and Web Vitals send optional transient context, with the HTTP `User-Agent` header used as a compatibility fallback for older trackers. Trusted server ingest uses the submitted URL and user agent. AI fetch uses its submitted path and user agent. QR opens use the resolved destination pathname and the request user agent.

Matching requests keep their normal accepted response. A browser or server ingest request is accepted but creates no analytics record. A matching QR open still redirects to its resolved destination without recording the open. Responses and logs do not reveal which rule matched.

Network rules retain their early suppression behavior. This means malformed traffic already blocked by CIDR or country policy keeps its existing accepted response instead of exposing payload validation details. The full path and user-agent check runs after decoding when that context is available.

Excluded records do not store derived country, region, city, provider, or ASN metadata, and HitKeep never stores the raw visitor IP for analytics.

## Finding your current IP

API reference:

- [Get the current resolved client IP](https://hitkeep.com/api/#tag/user/GET/api/user/current-ip)

This endpoint returns the IP address HitKeep sees for your current connection, accounting for trusted proxy headers if configured. The instance, team, and site editors provide the same current-IP CIDR helper.

## Related

- [Trusted Proxies](https://hitkeep.com/guides/installation/trusted-proxies/)
- [Bot and Spam Filtering](https://hitkeep.com/guides/tracking/spam-filtering/)
- [Permissions & Roles](https://hitkeep.com/guides/admin/permissions/)
- [Configuration Reference](https://hitkeep.com/reference/configuration/)
- [REST API Reference](https://hitkeep.com/api/)

[Previous QR campaigns](https://hitkeep.com/guides/tracking/qr-campaigns/)[Next Bot and spam filtering](https://hitkeep.com/guides/tracking/spam-filtering/)