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:

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.

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.

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

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:

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