General
Integrations
How to
Configuration
APIBeta
Stats
The Stats endpoint let's you run queries against the analytics data for your sites on Panelbear. It's the same query engine used to power the real time dashboards.
You can query the visitor count during the last hour, breakdown by top browsers, countries, and even apply query filters to narrow down your search for a particular segment.
Available query types
Panelbear supports the following kinds of queries: aggregation
, breakdown
, and timeseries
. Combined, they power all dashboard features, and you can access them directly via the stats API endpoint.
The stats endpoint is subdivided by query kind (/v1/stats/<query_kind>
). You can jump into the docs for each query type here:
- Aggregation: Aggregate the results into one or more metrics (eg. total views).
- Timeseries: Slice the query results over a time bucket (eg. views per day of the month).
- Breakdown: Group the results by a breakdown field (eg. views by browser).
Querying basics
The data points Panelbear collects are called "events". You can think of each event as an entry with one or more "dimensions" about an interaction on your website. These dimensions can be things like the browser name, operating system, the page visited, visitor country, and so on.
Panelbear can typically process millions of datapoints within a second, and automatically applies various optimization techniques the more traffic you get. This ensures your queries remain fast even as you grow into millions of monthly visits. That way you can focus on understanding your data, and we'll do the heavy lifting for you.
When you run a query, Panelbear quickly scans a data structure containing all events for your site, applying any filters you specify and aggregating the metrics you requested. The results of this query are then shown to you as a JSON response.
You can build powerful queries via HTTP calls to any of the stats endpoints. The query should be sent over a POST request, encoded as JSON in the request body.
All stats queries have the following form:
$ curl -X POST \ -H "Authorization: Bearer <TOKEN>" \ -H "Content-type: application/json" \ "https://api.panelbear.com/v1/stats/<query_kind>" \ -d '{ ... }' # Query-specific JSON payload < HTTP/1.1 200 OK < Content-Type: application/json { "data": { ... } # Results }
Where the JSON-encoded query might look something like this (assuming you replace <SITE_ID>
with your own site's ID):
{ "site_id": "<SITE_ID>", "period": "1h", "aggregate": ["event_count"], "filter": [ { "dimension": "event_name", "operator": "eq", "value": "Pageview" }, { "dimension": "browser", "operator": "eq", "value": "Safari" } ] }
For the query above, Panelbear will count all Pageview
events on your site that happened within the last hour, and originated from a Safari
browser.
// The query result { "data": { "event_count": { "value": 135 } } }
The Query object
All queries are described with some combination of these main parameters:
Field | Description |
---|---|
site_id | The ID of the site to query. |
period | The time window to aggregate. See time periods for valid values. |
aggregate | The dimensions to aggregate into query results. |
group_by | The dimension to group the results by (breakdown query only). |
order_by | The dimensions to order the results by (breakdown query only). |
filter | The filters to apply before computing the aggregations. |
timezone | Timezone to use for all time window calculations. For example: America/Costa_Rica . Defaults to UTC . Refer to the TZ database name list for possible timezone names. |
For example, this is what a breakdown
query might look like.
{ "period": "today", "group_by": "country", "aggregate": ["visitor_count", "page_load_avg"], "filter": [ { "dimension": "path", "operator": "eq", "value": "/blog/launching-new-product" }, { "dimension": "browser", "operator": "eq", "value": "Firefox" } ] }
First-class support for custom events
In Panelbear, all events are first-class objects. That means if you send custom events such as NewsletterSignup
, it will be recorded and stored alongside Pageview
events on your site.
You can make use of any event dimension available. For example your custom events can report any dimension just like a pageview, this includes page load times, UTM parameters, countries, network timings, and so on.
Additionally, Panelbear automatically applies the same ingestion rules and anonymization techniques to all events, not just pageviews. That way you can simply report events, and query them in aggregate, without tracking individuals.
Querying pageviews only
If you want to only count Pageviews
in your queries you should add a event name filter. Otherwise all events you're reporting will be counted (eg. NewsletterSignup
will also count towards your results).
To filter for Pageview
events, simply add a query filter on any of your queries. For example:
$ curl -X POST \ -H "Authorization: Bearer <TOKEN>" \ -H "Content-type: application/json" \ "https://api.panelbear.com/v1/stats/aggregation" \ -d '{ "site_id": "<SITE_ID>", "period": "24h", "aggregate": ["session_count", "event_count"], "filter": [ { "dimension": "event_name", "operator": "eq", "value": "Pageview" } ] }' < HTTP/1.1 200 OK < Content-Type: application/json { "data": { "session_count": { "value": 1417 }, "event_count": { "value": 2122 } } }
Time periods
All queries aggregate events that happened within a time window. You can control the size of this window via the period
parameter of the JSON query. By default it is set to 1h
(one hour), but you can set it to any value described below.
Period | Description |
---|---|
1h | One hour ago until now. |
24h | 24 hours ago until now. |
today | From 00:00 of the current day until 23:59:59. |
7d | 7 days ago until now. |
4w | 4 weeks ago until now. |
3m | 3 months ago until now. |
12m | 12 months ago until now. |
24m | 24 months ago until now. |
mtd | From the start of the current month until now. |
ytd | From the start of the current year until now. |
custom | A custom period, defined by the date_start and date_end parameters. |
Custom time periods
You can query for arbitrary time periods by setting the period parameter to custom
in combination with the date_start
and date_end
parameters (ISO 8601 datetime strings).
For example:
$ curl -X POST \ -H "Authorization: Bearer <TOKEN>" \ -H "Content-type: application/json" \ "https://api.panelbear.com/v1/stats/aggregation" \ -d '{ "site_id": "<SITE_ID>", "period": "custom", "date_start": "2021-01-01T00:00:00Z", "date_end": "2021-01-31T23:59:59Z", "aggregate": ["session_count", "event_count"], "filter": [ { "dimension": "event_name", "operator": "eq", "value": "Pageview" } ] }'
Dimensions
You can think of dimensions as the "fields" you're able to query and aggregate. They can be either computed (eg. total visitors or average load time), or part of the reported event (eg. country code or operating system).
The dimensions you can aggregate
, filter
, group_by
or order_by
depend on the query kind you're running.
Aggregation dimensions
You can use any of the following dimensions in the aggregate
field of the query. These correspond to the query result you wish to compute.
Dimension | Description |
---|---|
event_count | The count of events matching the query criteria. |
session_count | The count of unique sessions (or visitors). |
bounce_rate * | The percentage of sessions that only have one interaction on your site (eg. one pageview before leaving). |
conversion_rate | The percentage of unique sessions that match the query criteria, in relation to all sessions for the same period. |
events_per_session_avg | The average number of events per session. |
session_duration_avg * | The average session duration in seconds. |
page_load_{avg,p50,p75,p95} | The page load time in milliseconds. |
page_load_network_avg | The page load time attributed to the network (DNS + SSL + Connection + Download). |
page_load_frontend_avg | The page load time attributed to the frontend (DOM Content Load + DOM Render). |
page_load_backend_avg | The page load time attributed to the backend (Time to First Byte). |
* Only available in timeseries and aggregation queries. Not supported in the breakdown queries.
Breakdown and filtering dimensions
You can use any of the following dimensions in the filter
, order_by
, and group_by
fields of the query.
Dimension | Description |
---|---|
browser | Browser name. For example Firefox , Safari . |
connection_speed | Effective connection speed, as reported by standard browser APIs. One of slow-2g , 2g , 3g , 4g . |
country_code | Visitor country, as a two-charater country code in ISO 3166-1 Alpha 2 format. |
device_type | Normalized device type. One of desktop , mobile , tablet , bot , or other . |
event_name | Event name. It's Pageview for website pageviews, or any value you set if using custom events. |
os | Operating system name. For example Mac OS . |
path | The path component of the website URL. For example: /pricing . |
referrer_host | Referrer hostname. For example, if a visitor came throught Google Search, this would be set to google.com . |
utm_source | UTM source parameter. For example producthunt . |
utm_campaign | UTM campaign parameter. For example summer_sale . |
utm_medium | UTM medium parameter. For example email . |
Naming conventions
Some dimensions and aggregate metrics have word endings to help you understand what exactly are they counting. For example, while page_load_avg
refers to the average load time metric, page_load_p50
refers to the median (or 50th percentile) metric. For reference here's a list of all suffixes:
Name or suffix | Description |
---|---|
*_count | Total count. |
*_rate | Rate. As in "rate of change", or "bounce rate". |
*_avg | Average. |
*_p50 | 50th percentile. |
*_p75 | 75th percentile. |
*_p95 | 95th percentile. |
Filtering
You can add one or more filters to your queries via the filter
functionality. At the moment only eq
(equal) and ne
(not equal) are available as comparison operators.
You can filter by any of the following dimensions: country_code
, path
, os
, device_type
, browser
, referrer_host
, utm_source
, utm_campaign
, utm_medium
, connection_speed
, event_name
.
Here's some example filters you might find within a query:
"filter": [ // event_name equals "Pageview" { "dimension": "event_name", "operator": "eq", "value": "Pageview" }, // path not equals "/pricing" { "dimension": "path", "operator": "ne", "value": "/pricing" }, // country_code equals "US" { "dimension": "country_code", "operator": "eq", "value": "US" } ]
Next steps
You can refer to query-specific documentation via the following links:
- Aggregation: Aggregate the results into one or more metrics (eg. total views).
- Timeseries: Slice the query results over a time bucket (eg. views per day of the month).
- Breakdown: Group the results by a breakdown field (eg. views by browser).