Docs
Explorar la documentación

API filters and date periods

One filter syntax for the dashboard, the API, MCP and exports. Learn the period, comparison and segment inputs and how to combine conditions with AND and OR.

Ver como Markdown

Every stats operation accepts the same inputs:

Parameter Description
period today, yesterday, 24h, 7d, 14d, 28d, 30d (default), 90d, mtd, last_month, qtd, last_quarter, ytd, 12mo, last_year, all, custom
from, to Dates (YYYY-MM-DD, inclusive) in the site's timezone, with period=custom
compare none (default), previous_period, previous_year, custom
compare_from, compare_to With compare=custom
match_weekday true to align the comparison by day of the week
filters See below
segment_id Apply a saved segment (seg_…), combined with filters

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.

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

In URLs, send it URL-encoded:

sh 
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.

Operators#

Operator Value Meaning
is, is_not a string Equals / doesn't equal
any_of, none_of a list Equals one of / none of
contains, not_contains a string Case-insensitive substring
starts_with a string Prefix
regex, not_regex a string Regular expression
gt, lt a number Greater / less than (numeric properties)
between [min, max] Inclusive range (numeric properties)

Dimensions#

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

Dimension Label Scope
channel Channel Visit (first touch)
referrer Referrer Visit (first touch)
referrer_url Referrer URL Visit (first touch)
utm_source UTM source Visit (first touch)
utm_medium UTM medium Visit (first touch)
utm_campaign UTM campaign Visit (first touch)
utm_content UTM content Visit (first touch)
utm_term UTM term Visit (first touch)
ref Ref Visit (first touch)
hostname Hostname Visit (first touch)
country Country Visit (first touch)
language Language Visit (first touch)
device Device Visit (first touch)
browser Browser Visit (first touch)
browser_version Browser version Visit (first touch)
os Operating system Visit (first touch)
os_version OS version Visit (first touch)
screen Screen size Visit (first touch)
entry_page Entry page Visit only
exit_page Exit page Visit only
interaction Interaction Visit only
page Page Event / page
event Event Event / page
goal Goal Goal
prop:<key> Custom property value, e.g. prop:plan Event
  • 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.
  • Event / page: page filters visits that viewed a page, and event filters visits in which an event happened.
  • Goal: ["goal", "is", "<goal id>"] filters visits that converted.
  • Properties: prop:<key>, e.g. ["prop:plan", "is", "pro"], or ["prop:seats", "gt", 5].

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, or an invalid regex returns 422 validation_failed with the reason in message. Filters that aren't valid JSON return 400 bad_request.