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.

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, 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
A limit on the number of rows returned. If you group by a high-cardinality field (e.g. pathname), you should set a limit to keep responses fast.
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, 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.

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"
    }
]

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
        }
    ]
}