API filters and date periods

Every stats operation accepts the same inputs:

Periods#

All periods are whole days in the site's timezone, except 24h.

Comparisons#

Syntax#

filters is a JSON array. Each item is a condition [dimension, operator, value]. Items are combined with AND. Wrap conditions in {"any": [...]} to combine them with OR.

[
  ["page", "starts_with", "/blog"],
  ["country", "any_of", ["DE", "FR", "NL"]],
  { "any": [["channel", "is", "email"], ["utm_medium", "is", "newsletter"]] }
]

In URLs, send it URL-encoded:

curl -G "https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/stats/aggregate.json" \
  --data-urlencode 'filters=[["page","starts_with","/blog"],["country","any_of",["DE","FR"]]]' \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

In JSON bodies and MCP tool calls, pass the array itself. Conditions can also be objects: {"dimension": "page", "operator": "is", "value": "/"}.

Limits: 20 conditions in total, regular expressions up to 200 characters. An any group needs at least one condition.

Operators#

For wildcard and not_wildcard, * is the only special character and the whole value must match, so ["page", "wildcard", "/blog/*"] matches every blog page. page values include a query parameter only when the site keeps it (Site settings, Privacy), stored in alphabetical order, e.g. /blog?page=3&sort=new.

gt, lt and between compare numbers, so they are meant for numeric properties (prop:<key>). A stored value that isn't a number never matches.

Dimensions#

The same keys are used for filters and for /sites/{site_id}/breakdown/{dimension}.

• Visit (first touch) dimensions describe how a visit started. Events carry their visit's values, so "country is DE" works for events too.
• Visit only: entry and exit pages, and interaction: whether the tracker saw a real input (a pointer, key, touch or wheel event) during the visit. Its values are seen, none and unknown (the visit can't tell, for example data from before 1 October 2026). And bot_score: how likely the visit came from a bot, as likely_human, unsure, likely_bot or not_scored (see Advanced Bot Detection).
• Event / page: page filters visits that viewed a page, and event filters visits in which an event happened.
• Goal: ["goal", "is", "goal_…"] filters visits that converted. The value is the goal's id. Use is or any_of for visits that converted, and is_not or none_of for visits that didn't. An unknown or archived goal id matches nothing.
• Properties: prop:<key>, e.g. ["prop:plan", "is", "pro"], or ["prop:seats", "gt", 5]. The key is 1 to 64 lowercase letters, digits or underscores.

interaction and bot_score (Traffic quality) need the Pro plan or above. On Free a breakdown by one responds with 402 plan_limit, and a filter on one is left out of the query, so the result counts every visit.

Channel values are the keys listed in Channels (organic_search, ai_assistants…). Countries are ISO 3166-1 alpha-2 codes. There are no region or city dimensions.

Errors#

An unknown dimension or operator, a list operator without a list, a number operator without a number, an invalid regex, or filters that isn't a JSON array returns 422 validation_failed with the reason in message. An unknown period, compare or interval value returns 422 too.