Fathom Analytics

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

Create an event. **Permissions:** Requires write access to the site (`manage:{site_id}`). **Returns:** An event object.

Create a milestone. Returns HTTP `201 Created` on success. **Permissions:** Requires write access to the site (`manage:{site_id}`). **Returns:** A milestone object.

Create a site. **Permissions:** Requires full account access (`*`). **Returns:** A site object.

Returns the total number of current visitors on a site. The detailed view also returns the top 150 pages and top 150 referrers. **Permissions:** Requires read access to the site (`all-sites-readonly`, `read:{site_id}` or `manage:{site_id}`). **Returns:** The current visitor count, with an optional detailed breakdown.

Delete an event. Careful — you can't undo this, and neither can we. **Permissions:** Requires write access to the site (`manage:{site_id}`). **Returns:** Returns a deleted object on success. Otherwise, this call returns an error.

Delete a milestone. Careful — you can't undo this, and neither can we. **Permissions:** Requires write access to the site (`manage:{site_id}`). **Returns:** Returns a deleted object on success. Otherwise, this call returns an error.

Delete a site. Careful — you can't undo this, and neither can we. **Permissions:** Requires full account access (`*`). **Returns:** Returns a deleted object on success. Otherwise, this call returns an error.

Retrieve information about the account that owns the API key. **Permissions:** Requires a token with full account access (the `*` scope). **Returns:** An account object.

Return a single event. **Permissions:** Requires read access to the site (`all-sites-readonly`, `read:{site_id}` or `manage:{site_id}`). **Returns:** An event object.

Return a single milestone. **Permissions:** Requires read access to the site (`all-sites-readonly`, `read:{site_id}` or `manage:{site_id}`). **Returns:** A milestone object.

Return a single site. **Permissions:** Requires read access to the site (`all-sites-readonly`, `read:{site_id}` or `manage:{site_id}`). **Returns:** A site object.

Retrieve metadata about the API token used to make the request, including its name, permissions (abilities), token-format version and timestamps. Your secret token value is never returned. **Permissions:** Any valid API token. **Returns:** A token object.

Return a list of all events this site owns. Events are sorted by `created_at` ascending to allow you to paginate with ease. **Permissions:** Requires read access to the site (`all-sites-readonly`, `read:{site_id}` or `manage:{site_id}`). **Returns:** A list of event objects. > The `currency` field is only populated on Create and Update responses; it is returned as `null` on list and get responses.

Return a list of all milestones this site owns. Milestones are sorted by `created_at` ascending to allow you to paginate with ease. **Permissions:** Requires read access to the site (`all-sites-readonly`, `read:{site_id}` or `manage:{site_id}`). **Returns:** A list of milestone objects.

Return a list of all sites this API key owns. Sites are sorted by `created_at` ascending to allow you to paginate with ease. **Permissions:** Requires read access to all sites (`all-sites-readonly`) or full account access. **Returns:** A list of site objects.

Update an event. Send only the fields you want to change. **Permissions:** Requires write access to the site (`manage:{site_id}`). **Returns:** An event object.

Update a milestone. Both `name` and `milestone_date` are required. **Permissions:** Requires write access to the site (`manage:{site_id}`). **Returns:** A milestone object.

Update a site. Send only the fields you want to change. **Permissions:** Requires write access to the site (`manage:{site_id}`). **Returns:** A site object.

Previously wiped all completion data belonging to an event. This endpoint is no longer available.

Previously wiped all pageviews and event completions from a website. This endpoint is no longer available.