Time windows, filters and comparisons

The analytics endpoints share one set of query parameters: a time window (with its time zone and bucket size), an optional comparison, filters and a saved segment. Each endpoint's reference page lists which of them it takes.

curl -G -H "Authorization: Bearer $PILOTFOX_API_KEY" \
  "https://pilotfox.app/api/v1/sites/SITE_ID/timeseries" \
  --data-urlencode 'start=2026-10-01' \
  --data-urlencode 'end=2026-10-07' \
  --data-urlencode 'tz=America/New_York' \
  --data-urlencode 'compare=year' \
  --data-urlencode 'metrics=visitors,pageviews' \
  --data-urlencode 'filters=[{"dim":"country","op":"eq","values":["US","CA"]}]'

-G --data-urlencode makes curl put each parameter in the query string, URL-encoded; filters hold JSON, which must be encoded.

Time windowCopy Anchor Link

Send exactly one of these forms; none, or two of them, is a 400:

start and end must both be dates or both be instants, within the years 1970 to 2299.

The resolved window comes back in meta.window: from and to as UTC instants (from is null for all=true), the time zone and the bucket.

Time zoneCopy Anchor Link

tz is an IANA time zone name, such as Europe/London or America/New_York, or UTC. Without it, the site's own time zone applies (set in the site settings). It decides where days begin for date windows, day and longer buckets, and the hour-of-week heatmap. Offsets (+02:00) and abbreviations (CET, EST) are refused. meta.window.tz holds the canonical name the server used, which can differ in spelling from the one you sent (for example an older alias).

BucketCopy Anchor Link

Time series group their points by bucket: minute, 5m, 15m, hour, day, week (ISO weeks, starting on Monday), month or year. Without it, PilotFox picks one from the window's length:

A window may hold at most 1 500 buckets: last=30d&bucket=minute is a 400 (too many buckets: 43200 minute buckets (max 1500)). Each point's t is the start of its bucket, as an ISO 8601 instant.

ComparisonCopy Anchor Link

Ask for the same report over an earlier window, computed in the same request:

compare cannot be combined with compare_start/compare_end, nor any of them with all=true. The comparison uses the same time zone, bucket and filters.

These endpoints take a comparison: /overview, /timeseries, /goals/stats, /revenue/summary, /revenue/timeseries, /revenue/subscriptions/summary and the Search Console reports. The other endpoints compute no comparison.

The answer carries the comparison window in meta.compare, and the earlier values under previous: one object for a summary, and on each point of a time series (null where the comparison series has fewer points):

{
  "data": {
    "visitors": 8,
    "pageviews": 7,
    "previous": { "visitors": 0, "pageviews": 0 }
  },
  "meta": {
    "window": { "from": "2026-10-20T20:38:30.486Z", "to": "2026-10-27T20:38:30.486Z", "tz": "Europe/Berlin", "bucket": "day" },
    "compare": { "from": "2026-10-13T20:38:30.486Z", "to": "2026-10-20T20:38:30.486Z" }
  }
}

FiltersCopy Anchor Link

filters is a JSON array of conditions, URL-encoded into one query parameter. A condition is an object { "dim", "op", "values" }:

[
  { "dim": "pathname", "op": "starts_with", "values": ["/blog"] },
  { "dim": "country", "op": "eq", "values": ["US", "CA"] },
  { "dim": "prop:plan", "op": "neq", "values": ["free"] }
]

• Conditions combine with AND. Every condition must hold.
• Values combine with OR for the positive operators (country eq US or CA), and as none of for the negative ones (neq, not_contains, not_regex: matches none of the values).
• Limits: at most 20 conditions, 50 values per condition, 500 characters per value and 300 per regular expression.

OperatorsCopy Anchor Link

A value of the wrong type is a 400 naming the problem, for example gt takes exactly one number. For asn, 0 means unknown: asn lt 2000 does not match visitors whose network is unknown.

DimensionsCopy Anchor Link

Session dimensions describe a visit as a whole. Text attributes such as the referrer and the UTM tags are taken from the session's first event that has them; the channel is the first one other than Direct or Internal, if any.

Event dimensions describe single events:

How event conditions apply. A report about visits (visitors, sessions, bounce rate, breakdowns by a session dimension) counts the sessions that pass every session condition and have at least one event matching each event condition, or, for a negative operator, no matching event at all. All events of those sessions then count. A report about events (event lists, pages, event and error summaries) also keeps only the events that match.

An unknown dimension is a 400 (Unknown dimension: colour).

Dimensions that need sessions:readCopy Anchor Link

Some dimensions single out a person, or hold values that only the endpoints for individual sessions return (a query string can carry a password-reset token or a payment id). Counting matches under starts_with or regex would spell such a value out one character at a time, so filtering by them needs the sessions:read permission on the site:

This applies to API keys without sessions:read, to share links without that scope and to everyone reading a public site, and also to the conditions of a segment they apply. prop:ref is the checkout reference that links payments to visits; prop:message, prop:stack and prop:file hold the text of errors (whatever the event name, since a condition names no event).

Breakdown dimensionsCopy Anchor Link

/breakdown groups by one session dimension, dim, and ranks the rows by metric (visitors by default, or sessions, pageviews, bounce_rate, avg_session_duration). Every session dimension above works except visitor_id, user_id, identified, geo_point and geo_h3, which are for filtering only.

curl -G -H "Authorization: Bearer $PILOTFOX_API_KEY" \
  "https://pilotfox.app/api/v1/sites/SITE_ID/breakdown" \
  --data-urlencode 'last=7d' \
  --data-urlencode 'dim=channel' \
  --data-urlencode 'filters=[{"dim":"pathname","op":"starts_with","values":["/pricing"]}]'

{
  "data": [
    { "value": "Direct", "visitors": 1, "sessions": 1, "pageviews": 1, "bounce_rate": 100, "avg_session_duration": 0, "percentage": 100 }
  ],
  "meta": {
    "window": { "from": "2026-10-20T20:22:06.165Z", "to": "2026-10-27T20:22:06.165Z", "tz": "Europe/Berlin", "bucket": "day" },
    "totalCount": 1,
    "cache": "miss"
  }
}

SegmentsCopy Anchor Link

A segment is a saved set of filter conditions (see /segments). Apply one with its id:

curl -G -H "Authorization: Bearer $PILOTFOX_API_KEY" \
  "https://pilotfox.app/api/v1/sites/SITE_ID/pages" \
  --data-urlencode 'last=30d' \
  --data-urlencode 'segment=a6d33c2c-6cf1-4850-96e4-f7ad3620d242' \
  --data-urlencode 'filters=[{"dim":"device_type","op":"eq","values":["mobile"]}]'

• The segment's conditions come first, then those of filters; a condition repeated exactly is used once. Together they may hold at most 20 conditions (Too many filters after applying the segment (max 20)).
• An API key can apply the organization's shared segments (those saved as public), whether saved for the whole organization or for this site. Private segments belong to the person who saved them; anyone else, a key included, gets 404 Segment not found, as for an id that does not exist.
• The sessions:read rule applies to the segment's conditions too.

Every endpoint that takes filters also takes segment.

Other parametersCopy Anchor Link

Endpoints add their own parameters, such as dim and metric on breakdowns, metrics on /timeseries (a comma list of the metrics to return), goal (a goal id, to count its conversions alongside) on breakdowns, pages, geography and journeys, and the paging parameters. Their reference pages list them.

The query string, all parameters together, must stay under 16 KB, or the server answers 431. That is far more than 20 conditions normally need.