Stats Breakdown

The breakdown query lets you group events by a specific dimension before computing the aggregated metrics.

For example, some of the things you can compute with this query are:

Unique visitors and pageviews per page.
Page load time statistics by country.
Average visit duration by referrer.
Average pages per visit by browser.

Endpoint

POST /v1/stats/breakdown

This endpoint responds with 200 - Success if successful, and will include a JSON object a list of entries grouped by the breakdown field.

JSON Parameters

Field	Type	Description
`site_id`	string	The Site ID to query. required
`aggregate`	string list	A list of dimensions to aggregate on. required
`group_by`	string	The breakdown dimension to group the results by. required
`period`	string	The time window to aggregate. See time periods for valid values. Default: `1h`. optional
`filter`	object list	List of query filters to apply. optional
`order_by`	string list	The list of dimensions to order the results by. optional
`timezone`	string	Timezone to use for all time window calculations. For example: `America/Costa_Rica`. Refer to the list of timezones for possible timezone names. Default: `UTC`. optional
`page`	number	The page number. Default: `1`. optional
`page_size`	number	The page size. Default: `10`. optional

Sorting and pagination

Sometimes the result of breakdown queries can be quite large. That's where pagination and ordering come in handy. You can order the query results by almost any dimension you want.

You can select up to 2 order_by dimensions. By default they use ascending order, but you can select descending order by using the - suffix (eg. -count means "order by count descending", while event_count means "order by count ascending").

For example, the following query orders the results first by unique session count in descending order (-session_count), and in case of a tie by browser name ascending (browser). We request the second page of results in this example.

{
  "site_id": "<SITE_ID>",
  "period": "24h",
  "aggregate": ["session_count"],
  "group_by": "browser",
  "order_by": ["-session_count", "browser"],
  "page": 2
}

Examples

Unique visitors by country

The following JSON query returns the unique visitor count over the past 24 hours for your given <SITE_ID>, grouped by country.

$ curl -X POST \
       -H "Authorization: Bearer <TOKEN>" \
       -H "Content-type: application/json" \
       "https://api.panelbear.com/v1/stats/breakdown" \
       -d '{
            "site_id": "<SITE_ID>",
            "period": "24h",
            "aggregate": ["session_count"],
            "group_by": "country_code"
        }'

< HTTP/1.1 200 OK
< Content-Type: application/json
{
	"data": [
        {
			"country_code": "US",
			"session_count": 1571
		},
        {
			"country_code": "DE",
			"session_count": 1502
		},
        {
			"country_code": "CA",
			"session_count": 1495
		}
	],
	"result_count": 3,
	"page": 1,
	"page_size": 10,
	"page_count": 1
}

Count unique visitors by browser, and averate load time

The following query returns the total visitor count and average page load time by browser over the past 24 hours, filtered to the /pricing page and only visits coming from the United States (US).

We also filter for Pageview events only, to ensure no custom events are included in the calculations. This is because we're only interested in pageview actions.

$ curl -X POST \
       -H "Authorization: Bearer <TOKEN>" \
       -H "Content-type: application/json" \
       "https://api.panelbear.com/v1/stats/breakdown" \
       -d '{
            "site_id": "<SITE_ID>",
            "period": "24h",
            "aggregate": [
                "session_count",
                "page_load_avg"
            ],
            "group_by": "browser",
            "order_by": ["-session_count", "browser"],
            "filter": [
                {
                    "dimension": "event_name",
                    "operator": "eq",
                    "value": "Pageview"
                },
                {
                    "dimension": "path",
                    "operator": "eq",
                    "value": "/pricing"
                },
                {
                    "dimension": "country_code",
                    "operator": "eq",
                    "value": "US"
                }
            ]
        }'

< HTTP/1.1 200 OK
< Content-Type: application/json
{
	"data": [
        {
			"browser": "Firefox",
			"session_count": 1571,
			"page_load_avg": 981
		},
        {
			"browser": "Chrome",
			"session_count": 1502,
			"page_load_avg": 933
		},
        {
			"browser": "Safari",
			"session_count": 1495,
			"page_load_avg": 825
		}
	],
	"result_count": 3,
	"page": 1,
	"page_size": 10,
	"page_total": 1
}