How to get KPIs and metrics from the Fathom Analytics API

Fathom Analytics is a privacy-focused web analytics platform to track your website visitor, page view analytics and custom events and has a very powerful API and is modelled on Stripe's API. You can find their documentation here: Fathom's API.

Contents

• Authentication
• Endpoint
• How to get page view metrics from Fathom
• How to get event metrics from Fathom
• Fathom API Results

Authentication

For authentication you provide a Bearer token, which you can create for your account under the Settings > API page in Fathom.

Endpoint

To get metrics like page views from their API you use the aggregations endpoint. Fathom differentiates between pageview metrics such as visitors and page views and the event metrics.

• https://api.usefathom.com/v1/aggregations?entity=pageview
• https://api.usefathom.com/v1/aggregations?entity=events

How to get page view metrics from Fathom

For these requests the entity_id parameter is the id of the site you want to get data for. You can get this from your Sites page in Fathom.

https://api.usefathom.com/v1/aggregations?entity=pageview
  // Replace this with the id of the site
  &entity_id=SITE_ID
  // See options below
  &aggregates=visits
  // the following produces all hourly metrics for a specific date period
  &date_grouping=hour
  &sort_by=timestamp:asc
  &date_from=2024-01-01
  &date_to=2024-01-31

Options for aggregates parameter:

• visits: Number of unique visitors to this site see Fathom docs
• uniques: Number of unique page views to this site see Fathom docs
• pageviews: Number of all page views to this site see Fathom docs
• avg_duration: Number of seconds on average a user spent on the site see Fathom docs
• bounce_rate: Number of people who visited divided by number of people who left after visiting just one page see Fathom docs

How to get event metrics from Fathom

For these requests the entity_id parameter is the id of the event you want to get data for. You need to retrieve this from the list events endpoint as the new event types (introduced 2024) do not display the event id on the dashboard anymore.

https://api.usefathom.com/v1/aggregations?entity=pageview
  // Replace this with the id of the event
  &entity_id=EVENT_ID
  // See options below
  &aggregates=conversions
  // the following produces all hourly metrics for a specific date period
  &date_grouping=hour
  &sort_by=timestamp:asc
  &date_from=2024-01-01
  &date_to=2024-01-31

Options for aggregates parameter (see Fathom docs):

• conversions: Number of times the event was triggered
• unique_conversions: Number of times the event was triggered at least once by a user.
• value: Sum of the values (in cents) passed into the event.

Fathom API Results

The aggregates endpoint will return the following data:

{
  "object": "list",
  "url": "/v1/aggregations",
  "has_more": false,
  "data": [
    {
      "browser": "Chrome",
      "device_type": "Desktop",
      // depends on date_grouping
      "date": "2024-08-18 02:00:00",
      // for entity pageview depending on the aggregate property
      "visits": 123,
      "uniques": 123,
      "pageviews": 123,
      "avg_duration": 123,
      "bounce_rate": 123,
      // for entity event depending on the aggregate property
      "conversions": 123,
      "unique_conversions": 123,
      "value": 123
    },
    ...
  ]
}

As of September 2024 this endpoint does not have any pagination and returns all matching results for this query.