Fathom AnalyticsAPI

Command Palette

Search for a command to run...

v1

Reports

Generate flexible, ad-hoc reports across your data.

Aggregation#

GEThttps://api.usefathom.com/v1/aggregations

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

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.

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.
Grouped reports (field_grouping) default to 500 rows unless you set limit. The maximum is 1000, and this endpoint has no pagination. BI tools such as Looker Studio / Data Studio that fire many aggregations at once will hit the concurrency cap, not the row cap. Space those requests, cache one extract per period, or raise the API plan.

Query parameters

entitystringrequired
The entity you want to report on. Events are treated separately from pageviews. Supported values: pageview and event.
Options:pageviewevent
entity_idstringRequired when entity is "pageview"
When entity is pageview, this is the id of the site you want to aggregate on. When entity is event, you may instead pass the event's tracking code here.

Tip: for events, we recommend using site_id + entity_name instead of an event tracking code.
site_idstringRequired when entity is "event" and entity_id is omitted
The id of the site the event belongs to.
entity_namestringRequired when entity is "event" and entity_id is omitted
The name of the event you want to report on. Example: purchase.
aggregatesstringrequired
The aggregates you wish to include, separated by a comma.

Supported values for pageview entities: visits, uniques, pageviews, avg_duration and bounce_rate. The difference between "visits" and "uniques" is that visits are unique site visits whilst uniques are unique page visits.

Supported values for event entities: conversions, unique_conversions and value (value is returned in cents).
date_groupingstringoptional
By default, we don't do any date grouping and return total aggregations. Override this with hour, day, month or year. Note: hour grouping is only supported for date ranges of up to 7 days.
Options:hourdaymonthyear
field_groupingstringoptional
The fields you want to group by, separated by a comma (e.g. hostname,pathname). Supported values: hostname, pathname, entry_page, exit_page, referrer_hostname, referrer_pathname, referrer_source, browser, country_code, city, state, region, device_type, operating_system, utm_campaign, utm_content, utm_medium, utm_source, utm_term, keyword and ref.
sort_bystringoptional
The field you want to sort by, in the format field:asc|desc. You can use any field present in aggregates or field_grouping. When using date_grouping, you can also sort by timestamp:asc or timestamp:desc.
Example: pageviews:desc
date_fromstringoptional
Timestamp (e.g. 2022-04-01 15:31:00). Should match the timezone you're reporting in. Defaults to the entity's first recorded data.
date_tostringoptional
Timestamp (e.g. 2022-04-01 15:31:00). Should match the timezone you're reporting in. Default: now.
timezonestringoptionaldeprecated
Deprecated. We now report using each site's configured timezone by default. If provided, this TZ database name overrides the site's timezone for this request. We'll be removing this parameter in the future.
limitintegeroptional
Optional integer from 1 to 1000 inclusive.

Default. When field_grouping is set and you omit limit, we return at most 500 rows. When field_grouping is omitted, there is no default row cap. date_grouping alone does not trigger the 500 default.

Maximum. A limit above 1000 returns HTTP 400 with an errors.limit validation message. There is no pagination on this endpoint, so you cannot walk past 1000 grouped rows with a cursor. Narrow the result with filters and/or a shorter date_from / date_to, then issue more requests.
filtersarrayoptional
A JSON-encoded array of filter objects. See the filtering reference below for the full list of supported properties and operators. Each filter's value must be a string.

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

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.

GET
curl "https://api.usefathom.com/v1/aggregations?entity=pageview&aggregates=pageviews" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Response
[
    {
        "browser": "Chrome",
        "device_type": "Desktop",
        "pageviews": "30000"
    },
    {
        "browser": "Chrome",
        "device_type": "Mobile",
        "pageviews": "28000"
    },
    {
        "browser": "Chrome",
        "device_type": "Tablet",
        "pageviews": "24000"
    },
    {
        "browser": "Firefox",
        "device_type": "Desktop",
        "pageviews": "12000"
    },
    {
        "browser": "Firefox",
        "device_type": "Tablet",
        "pageviews": "5000"
    },
    {
        "browser": "Firefox",
        "device_type": "Mobile",
        "pageviews": "300"
    }
]
Filter: only include the /about page
[
    {
        "property": "pathname",
        "operator": "is",
        "value": "/about"
    }
]
Filter: exclude /register and /login
[
    {
        "property": "pathname",
        "operator": "is not",
        "value": "/register"
    },
    {
        "property": "pathname",
        "operator": "is not",
        "value": "/login"
    }
]
Filter: only include the United Kingdom
[
    {
        "property": "country_code",
        "operator": "is",
        "value": "GB"
    }
]
Filter: exclude /register or Desktop
[
    {
        "property": "pathname",
        "operator": "is not",
        "value": "/register"
    },
    {
        "property": "device_type",
        "operator": "is not",
        "value": "Desktop"
    }
]
Filter: only include visits that entered on /pricing
[
    {
        "property": "entry_page",
        "operator": "is",
        "value": "/pricing"
    }
]

Current visitors#

GEThttps://api.usefathom.com/v1/current_visitors

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

Returns the total number of current visitors on a site. The detailed view also returns the top 150 pages and top 150 referrers.

Query parameters

site_idstringrequired
The id of the site.
Example: CDBUGS
detailedbooleanoptional
Set to true for a detailed breakdown of pages and referrers. Otherwise you'll only get a count.
Default: false

Returns

The current visitor count, with an optional detailed breakdown.

GET
curl "https://api.usefathom.com/v1/current_visitors?site_id=CDBUGS" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Simple
{
    "total": 14
}
Detailed
{
    "total": 144,
    "content": [
        {
            "hostname": "bugsbunny.com",
            "pathname": "/spacejam",
            "total": 100
        },
        {
            "hostname": "bugsbunny.com",
            "pathname": "/blog/being-a-wabbit",
            "total": 44
        }
    ],
    "referrers": [
        {
            "referrer_hostname": "https://usefathom.com",
            "referrer_pathname": "/why-we-love-bugs-bunny",
            "total": 50
        },
        {
            "referrer_hostname": "https://daffyduck.com",
            "referrer_pathname": "/blog/i-am-sick-of-his-antics",
            "total": 32
        }
    ]
}