---
title: "Aggregation"
method: GET
path: "/aggregations"
tags: ["Reports"]
---

# Aggregation

`GET /aggregations`

Generate an aggregation. This is an incredibly flexible report that allows you to group on any fields you wish, and filter them at your leisure.

**Permissions:** Requires read access to the relevant site (`all-sites-readonly`, `read:{site_id}` or `manage:{site_id}`).

**Returns:** Returns an array of objects. The properties of each object vary based on the aggregates and groupings you've asked for. All numeric values are returned as strings.

> This API endpoint is only accurate on data from March 2021 onwards. Before then, we did not tie browser, country, pathname, etc. together, so we have no way to offer this advanced filtering on that data.

#### Filtering

Filters are supplied as a JSON array. Each filter is an object with a `property`, an `operator` and a string `value`. You can add as many filters as you like; see the examples in the code panel.

We support the following operators:

- `is` — exact match
- `is not` — everything except an exact match
- `is like` — contains the term (supports wildcards `*`)
- `is not like` — does not contain the term
- `matching` — matches a regular expression (regex) pattern
- `not matching` — does not match a regex pattern

**Operator availability depends on the field.** Text-style fields support all six operators; categorical fields support only `is` and `is not`:

- **All six operators:** `domain`, `hostname`, `pathname`, `entry_page`, `exit_page`, `referrer_hostname`, `referrer_pathname`, `referrer_source`, `ref`, `utm_campaign`, `utm_source`, `utm_medium`, `utm_content`, `utm_term`
- **`is` / `is not` only:** `device_type`, `operating_system`, `browser`, `country_code`, `city`, `state`, `region`

Note: `domain` can be filtered on but not grouped by, while `keyword` can be grouped by but not filtered on.

##### Entry and exit pages

`entry_page` is the pathname of the first pageview in a visit. `exit_page` is the pathname of the last pageview before the visitor leaves. Both are session-level fields — they mirror the Entry Pages and Exit Pages reports on your dashboard and work for both `field_grouping` and `filters`.

When you filter by `entry_page`, only visits that *entered* on that page are included. A visitor who lands on `/home` and later views `/pricing` is excluded by `{"property": "entry_page", "operator": "is", "value": "/pricing"}`, but included when filtering on `pathname` instead.

##### Regex examples

With `matching` / `not matching` you can build sophisticated filters:

- `^/(about|contact|pricing)$` — match only /about, /contact and /pricing
- `^/(about|contact|pricing)` — match paths starting with those
- `^/blog/\d{4}/\d{2}/` — match blog URLs like /blog/2025/07/my-post
- `^/products/[^/]+/$` — match product category pages

## Query parameters

- `entity` 'pageview' | 'event', required
- `entity_id` string
- `site_id` string
- `entity_name` string
- `aggregates` string, required
- `date_grouping` 'hour' | 'day' | 'month' | 'year'
- `field_grouping` string
- `sort_by` string
- `date_from` string
- `date_to` string
- `timezone` string
- `limit` integer

## Response `200`

Successful response

## Other responses

- `400` — Bad request. Returned for validation failures and other request problems. Send `Accept: application/json` to receive errors as JSON.
- `401` — Authentication failed — the API token is missing, malformed or invalid.

---

[API](https://skmtc.net/usefathom/apis/fathom-analytics-api.md) · [All operations](https://skmtc.net/usefathom/apis/fathom-analytics-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usefathom/fathom-analytics-api/revisions/50679caad756/schema)