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:

FieldDescription
site_idThe ID of the site to query.
periodThe time window to aggregate. See time periods for valid values.
aggregateThe dimensions to aggregate into query results.
group_byThe dimension to group the results by (breakdown query only).
order_byThe dimensions to order the results by (breakdown query only).
filterThe filters to apply before computing the aggregations.
timezoneTimezone 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.

PeriodDescription
1hOne hour ago until now.
24h24 hours ago until now.
todayFrom 00:00 of the current day until 23:59:59.
7d7 days ago until now.
4w4 weeks ago until now.
3m3 months ago until now.
12m12 months ago until now.
mtdFrom the start of the current month until now.
ytdFrom the start of the current year until now.

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.

DimensionDescription
event_countThe count of events matching the query criteria.
session_countThe 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_rateThe percentage of unique sessions that match the query criteria, in relation to all sessions for the same period.
events_per_session_avgThe 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_avgThe page load time attributed to the network (DNS + SSL + Connection + Download).
page_load_frontend_avgThe page load time attributed to the frontend (DOM Content Load + DOM Render).
page_load_backend_avgThe 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.

DimensionDescription
browserBrowser name. For example Firefox, Safari.
connection_speedEffective connection speed, as reported by standard browser APIs. One of slow-2g, 2g, 3g, 4g.
country_codeVisitor country, as a two-charater country code in ISO 3166-1 Alpha 2 format.
device_typeNormalized device type. One of desktop, mobile, tablet, bot, or other.
event_nameEvent name. It's Pageview for website pageviews, or any value you set if using custom events.
osOperating system name. For example Mac OS.
pathThe path component of the website URL. For example: /pricing.
referrer_hostReferrer hostname. For example, if a visitor came throught Google Search, this would be set to google.com.
utm_sourceUTM source parameter. For example producthunt.
utm_campaignUTM campaign parameter. For example summer_sale.
utm_mediumUTM 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 suffixDescription
*_countTotal count.
*_rateRate. As in "rate of change", or "bounce rate".
*_avgAverage.
*_p5050th percentile.
*_p7575th percentile.
*_p9595th 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).