Fathom Analytics API

The Fathom Analytics API allows you to take complete control of your Fathom account. You can control all entities within the account and generate ad-hoc custom reports. It's an incredibly powerful API, and we've tried to cater to every possible use case.

Each API request counts against your total monthly pageviews. So if you make 10 Create Site requests, that will count in the same way that 10 pageviews would. We do this because we want to give you the flexibility to use our API how you wish, and we want to ensure it's sustainable without us having to raise plan prices.

When running complex aggregation queries that are unique (haven't been run before by any user), you will experience a slight lag for the first time you run the query. This is because our database engine has to create a "query plan", to find the most optimal way to run what you're asking for. After that, it will be rapid.

The rate limits for our API are:

  • 2000 requests per hour on entity endpoints.
  • 10 requests per minute on aggregations and currents.

Please note

See our community guidelines for guidance about what you can and can't do when creating plugins, integrations and connections to our API.

If there's anything you think we should add, please let us know at support@usefathom.com.

Create a token

To create a token for our API, go to https://app.usefathom.com/api and click Create new. Make sure you've first received instructions via email.

If you don't have instructions for the API and how early access works, ask for them via support@usefathom.com.

  1. Click Create new from the API page.
  2. Give your token a name, and set permissions (Admin, read only (all sites), or site-specific).
  3. Click Save changes.
  4. Write down your API token and save it in a safe place. You won't be able to retrieve your token once you navigate away from that page.

Remember, the API is currently in early access and is subject to change.

Create new API key

Authentication

To connect to our API, you must use the Authorization header. This can be obtained from your dashboard, under Settings -> API. Your API key has complete access to your account, so please protect it.

GET https://api.usefathom.com/v1/account
curl https://api.usefathom.com/v1/account \
-H "Authorization: Bearer API_TOKEN_HERE"

Pagination

All top-level API resources allow you to fetch records in bulk via our "list" methods. These list methods share a common pagination structure.

Fathom utilizes cursor-based pagination and, as you can tell, we've taken use inspiration from the incredible Stripe API documentation. So this will be familiar to a lot of you. You can paginate using either starting_after or ending_before.

  • When you use starting_after, we will sort records in chronological order, which will allow you to page from the start of time up until the current day.
  • And when you use ending_before, we will sort records in reverse chronological order, meaning we'll effectively work in reverse chronological order from the object ID you give us.

Query String Parameters

  • limit optional, default is 10

    A limit on the number of objects to be returned, between 1 and 100.

  • starting_after optional

    A cursor for pagination/navigation. starting_after is an object ID. For example, if you requested 10 site objects, and the last item in the list was ABCDEF, you would send your next request with starting_after=ABCDEF.

  • ending_before optional

    A cursor for pagination/navigation. ending_before is an object ID. For example, if you requested 10 site objects, and the first item in the list was ABCDEF, you would send your next request with ending_before=ABCDEF.

Returns

  • A list of Site objects.

Errors

When we detect an error in the request, we will return a HTTP 400 or 401 response, and a JSON payload with a single key (error) containing the error message. If you aren't receiving errors, make sure you've set "Accept: application/json" in your request headers.

Response
{
"error": "This token doesn't have permission to access this endpoint"
}

Issues

If you run into any issues, or have any ideas, please let us know. We want this API to be fast, sustainable and powerful, and we're all ears on making it better.

Get account

Retrieve information about the account that owns the API key.

Returns

  • A User object.

GET https://api.usefathom.com/v1/account
curl https://api.usefathom.com/v1/account \
-H "Authorization: Bearer API_TOKEN_HERE"
Response
{
"id": 500302232,
"object": "account",
"name": "Homer Simpson",
"email": "homer@simpsonsfamily.doh"
}

List Sites

Return a list of all sites this API key owns. Sites are sorted by created_at ascending to allow you to do pagination with ease.

Query String Parameters

  • limit optional, default is 10

    A limit on the number of objects to be returned, between 1 and 100.

  • starting_after optional

    A cursor for pagination/navigation. starting_after is an object ID. For example, if you requested 10 site objects, and the last item in the list was ABCDEF, you would send your next request with starting_after=ABCDEF.

  • ending_before optional

    A cursor for pagination/navigation. ending_before is an object ID. For example, if you requested 10 site objects, and the first item in the list was ABCDEF, you would send your next request with ending_before=ABCDEF.

Returns

  • A list of Site objects.

GET https://api.usefathom.com/v1/sites
curl https://api.usefathom.com/v1/sites \
-H "Authorization: Bearer API_TOKEN_HERE"
Response
{
"object": "list",
"url": "/v1/sites",
"has_more": false,
"data": [
{
"id": "CDBUGS",
"object": "site",
"name": "Bugs Bunny Portfolio",
"sharing": "none",
"created_at": "2020-07-27 12:01:01"
}
]
}

Get Site

Return a single site

URL Parameters

  • site_id required

    The ID of the site you wish to load. This is the same string you use in the tracking code.
    Example: CDBUGS

Returns

  • A site object.

GET https://api.usefathom.com/v1/sites/CDBUGS
curl https://api.usefathom.com/v1/sites/CDBUGS \
-H "Authorization: Bearer API_TOKEN_HERE"
Response
{
"id": "CDBUGS",
"object": "site",
"name": "Bugs Bunny Portfolio",
"sharing": "none",
"created_at": "2020-07-27 12:01:01"
}

Create Site

Create a site

Parameters

  • name required

    The name of the website. Any string (up to 255 characters) is acceptable, and it doesn't have to match the website URL
    Example: Daffy's Website

  • sharing optional

    The sharing configuration. Supported values are: none, private or public.
    Default: none

  • share_password optional

    When sharing is set to private, you must also send a password to access the site with.

Returns

  • A site object.

POST https://api.usefathom.com/v1/sites
curl https://api.usefathom.com/v1/sites \
-H "Authorization: Bearer API_TOKEN_HERE" \
-d name="Acme Inc"
Response
{
"id": "GCDFS",
"object": "site",
"name": "Acme Inc",
"sharing": "none",
"created_at": "2021-08-10 00:45:43"
}

Update Site

Update a site

URL Parameters

  • site_id required

    The ID of the site you wish to load. This is the same string you use in the tracking code.
    Example: CDBUGS

Payload Parameters

  • name optional

    The name of the website. Any string (up to 255 characters) is acceptable, and it doesn't have to match the website URL
    Example: Daffy's Website

  • sharing optional

    The sharing configuration. Supported values are: none, private or public.
    Default: none

  • share_password optional

    When sharing is set to private, you must also send a password to access the site with.

Returns

  • A site object.

POST https://api.usefathom.com/v1/sites/GCDFS
curl https://api.usefathom.com/v1/sites/GCDFS \
-H "Authorization: Bearer API_TOKEN_HERE" \
-d name="Acme Holdings Inc" \
-d sharing=private \
-d sharing=the-jean-genie
Response
{
"id": "GCDFS",
"object": "site",
"name": "Acme Holdings Inc",
"sharing": "private",
"created_at": "2021-08-10 00:45:43"
}

Wipe Site

Wipe all pageviews and event completions from a website. This would typically we used when you want to completely reset statistics or right before you launch a website (to remove test data).

URL Parameters

  • site_id required

    The ID of the site you wish to load. This is the same string you use in the tracking code.
    Example: CDBUGS

Returns

  • A site object.

DELETE https://api.usefathom.com/v1/sites/GCDFS/data
curl https://api.usefathom.com/v1/sites/GCDFS/data \
-H "Authorization: Bearer API_TOKEN_HERE" \
-X DELETE
Response
{
"id": "GCDFS",
"object": "site",
"wiped": true
}

Delete Site

Delete a site (careful, you can't undo this and neither can we)

URL Parameters

  • site_id required

    The ID of the site you wish to load. This is the same string you use in the tracking code.
    Example: CDBUGS

Returns

  • Returns a deleted object on success. Otherwise, this call returns an error.

DELETE https://api.usefathom.com/v1/sites/GCDFS
curl https://api.usefathom.com/v1/sites/GCDFS \
-H "Authorization: Bearer API_TOKEN_HERE" \
-X DELETE
Response
{
"id": "GCDFS",
"object": "site",
"deleted": true
}

List Events

Return a list of all events this site owns. Events are sorted by created_at ascending to allow you to do pagination with ease.

URL Parameters

  • site_id required

    The ID of the site you wish to load events for.
    Example: CDBUGS

Query String Parameters

  • limit optional, default is 10

    A limit on the number of objects to be returned, between 1 and 100.

  • starting_after optional

    A cursor for pagination/navigation. starting_after is an object ID. For example, if you requested 10 site objects, and the last item in the list was ABCDEF, you would send your next request with starting_after=ABCDEF.

  • ending_before optional

    A cursor for pagination/navigation. ending_before is an object ID. For example, if you requested 10 site objects, and the first item in the list was ABCDEF, you would send your next request with ending_before=ABCDEF.

Returns

  • A list of Event objects.

GET https://api.usefathom.com/v1/sites/CDBUGS/events
curl https://api.usefathom.com/v1/sites/CDBUGS/events \
-H "Authorization: Bearer API_TOKEN_HERE" \
Response
{
"object": "list",
"url": "/v1/sites/CDBUGS/events",
"has_more": false,
"data": [
{
"id": "signed-up-to-newsletter",
"object": "event",
"name": "Signed up to newsletter",
"site_id": "CDBUGS",
"created_at": "2020-08-21 15:24:00"
},
{
"id": "purchase-product",
"object": "event",
"name": "Purchase product",
"site_id": "CDBUGS",
"created_at": "2020-08-21 15:24:00"
}
]
}

Get Event

Return a single event

URL Parameters

  • site_id required

    The ID of the site that the event belongs to. This is the same string you use in the tracking code.
    Example: CDBUGS

  • event_id required

    The ID of the event you wish to track. You have to create this event first before sending us completions.
    Example: signed-up-to-newsletter

Returns

  • An event object.

GET https://api.usefathom.com/v1/sites/CDBUGS/events/signed-up-to-newsletter
curl https://api.usefathom.com/v1/sites/CDBUGS/events/signed-up-to-newsletter \
-H "Authorization: Bearer API_TOKEN_HERE"
Response
{
"id": "signed-up-to-newsletter",
"object": "event",
"name": "Signed up to newsletter",
"site_id": "CDBUGS",
"created_at": "2020-08-21 15:24:00"
}

Create Event

Create an event

URL Parameters

  • site_id required

    The ID of the site you wish to create an event for.
    Example: CDBUGS

Payload Parameters

  • name required

    The name of the event (up to 255 characters)
    Example: Purchase early access

Returns

  • An event object.

POST https://api.usefathom.com/v1/sites/CDBUGS/events
curl https://api.usefathom.com/v1/sites/CDBUGS/events \
-H "Authorization: Bearer API_TOKEN_HERE" \
-d name="Purchase early access" \
Response
{
"id": "purchase-early-access",
"object": "event",
"name": "Purchase early access",
"created_at": "2021-08-10 10:45:43"
}

Update Event

Create an event

URL Parameters

  • site_id required

    The ID of the site you wish to create an event for.
    Example: CDBUGS

Payload Parameters

  • name required

    The name of the event (up to 255 characters)
    Example: Purchase early access

Returns

  • An event object.

POST https://api.usefathom.com/v1/sites/CDBUGS/events
curl https://api.usefathom.com/v1/sites/CDBUGS/events \
-H "Authorization: Bearer API_TOKEN_HERE" \
-d name="Purchase early access" \
Response
{
"id": "purchase-early-access",
"object": "event",
"name": "Purchase early access",
"created_at": "2021-08-10 10:45:43"
}

Wipe Event

Wipe all completion data belonging to an event

URL Parameters

  • site_id required

    The ID of the site that the event belongs to.
    Example: CDBUGS

  • event_id required

    The ID of the event you wish to wipe.
    Example: signed-up-to-newsletter

Returns

  • An event object.

DELETE https://api.usefathom.com/v1/sites/GCDFS/events/purchase-early-access/data
curl https://api.usefathom.com/v1/sites/GCDFS/events/purchase-early-access/data \
-H "Authorization: Bearer API_TOKEN_HERE" \
-X DELETE
Response
{
"id": "purchase-early-access",
"object": "event",
"wiped": true
}

Delete Event

Delete an event (careful, you can't undo this and neither can we)

URL Parameters

  • site_id required

    The ID of the site you wish to load. This is the same string you use in the tracking code.
    Example: CDBUGS

  • event_id required

    The ID of the event you wish to delete.
    Example: signed-up-to-newsletter

Returns

  • Returns a deleted object on success. Otherwise, this call returns an error.

DELETE https://api.usefathom.com/v1/sites/GCDFS/events/purchase-early-access
curl https://api.usefathom.com/v1/sites/GCDFS/events/purchase-early-access \
-H "Authorization: Bearer API_TOKEN_HERE" \
-X DELETE
Response
{
"id": "purchase-early-access",
"object": "event",
"deleted": true
}

Aggregation

Generate an aggregation. This is effectively an unbelievably 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. Before then, we did not tie browser, country, pathname, etc. together, so we have no way to offer this advanced filtering on that data. If there's demand for it, we will build a legacy endpoint that allows simple aggregations on historical data.

Query String Parameters

  • entity required

    The entity you want to report on. Events are treated separately from pageviews. Supported values: pageview and event.
    Example: pageview

  • entity_id required

    The ID of the entity that you want to report on. If reporting on a site, you'd send the site ID. If reporting on an event, we'd need the event ID.

  • aggregates required

    The SUM 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 "visitors" and "uniques" is that visitors are unique site visits whilst uniques are unique page visits. So a single user can only have one "visit" to your site, but they can view 10 unique pages.

    Supported values for event entities: conversions, unique_conversions and value. Note: Value will be returned in cents.

  • date_grouping optional

    Default: none. By default, we don't do any kind of date grouping, and we offer "total" aggregations. You can override this but you still have limits such as: When grouping daily, you cannot aggregate over 6 months of data. Supported values: hour, day, month and year.

  • field_grouping optional

    The fields you want to group by. Supported values are hostname, pathname, referrer_hostname, referrer_pathname, browser, country_code, device_type, utm_campaign, utm_content, utm_medium, utm_source, utm_term, keyword, q, ref and s.

    You can group by multiple fields using a comma hostname,pathname.

  • sort_by optional

    The field you want to sort by. Format is: field:asc|desc. You can use any field that you've asked for in the aggregations and field_grouping options. If using date_grouping, you can also use timestamp:asc or timestamp:desc here, which allows you to sort by date.
    Example: pageviews:desc

  • timezone optional

    The timezone you want us to use in our queries. We store all data in UTC, and use that by default, but can support any timezone. The timezone you send should be a TZ database name.
    Default: UTC.

  • date_from optional

    Timestamp (e.g. 2022-04-01 15:31:00). This should match the timezone you specified.

  • date_to optional

    Timestamp (e.g. 2022-04-01 15:31:00). This should match the timezone you specified. Default: now

  • limit optional

    A limit on the number of entries to return. For example, if your site had 10,000 unique pathnames, and you had "pathname" in field_grouping, you might get 10,000 rows back by default. You should limit this to prevent timeouts. We have no limits for early access but we'll soon be introducing pagination for this endpoint, and setting a maximum amount of rows that can be returned.

  • filters optional

    JSON payload. An array of objects. You can add as many filters as you like.

    The filtering is hyper flexible and is best illustrated via some JSON payload examples to the right (or below if you're on a mobile).

    We support the following operators: is, is not, is like and is not like.

    You can filter on the following fields (properties):

    • hostname

      The hostname of the content viewed. Some sites have multiple hostnames and, whilst Fathom doesn't support that in the dashboard, the API does.
      Example: https://bugsbunny.ca

    • pathname

      The pathname of the content viewed. Leading slash is important.
      Example: /about

    • referrer_hostname

      The hostname of the referrer.
      Example: https://daffyduck.com

    • referrer_pathname

      The pathname of the referrer.
      Example: /friends

    • ref

      The ref of the inbound link. This isn't always used but companies like Producthunt will append ?ref=producthunt when they link to your website.
      Example: producthunt

    • device_type

      The device type. Unless you've been sending us custom device types, the supported values as Desktop, Phone and Tablet.
      Example: Desktop

    • browser

      The browser used. We don't track browser versions as we practice data minimization, and browser version can help isolate an individual (which we don't want to do). Typical values are Chrome, Safari, Firefox, Edge, Opera and IE.
      Example: Desktop

    • country_code

      The country code to filter by (2 letters).
      Example: UK

    • utm_campaign

      The UTM campaign.
      Example: relaunch

    • utm_source

      The UTM source.
      Example: twitter

    • utm_medium

      The UTM medium.
      Example: social

    • utm_content

      The UTM content.
      Example: blog-post-relaunch

    • utm_term

      The UTM term.
      Example: best+privacy+first+analytics+software

Returns

  • Returns an array of objects. Properties vary based on the data you've asked for.

GET https://api.usefathom.com/v1/aggregations
curl https://api.usefathom.com/v1/aggregations \
-H "Authorization: Bearer API_TOKEN_HERE" \
-d entity="pageview" \
-d entity_id="CDBUGS" \
-d aggregates="pageviews" \
-G
Response
{
"object": "list",
"url": "/v1/aggregations",
"has_more": false,
"data": [
{
"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,
},
]
}
Filters Example: Only include pageviews/events that occured on the /about page
[
{
"property": "pathname",
"operator": "is",
"value": "/pricing"
}
]
Filters Example: Exclude pageviews/events that occured on /register and /login
[
{
"property": "pathname",
"operator": "is not",
"value": "/register"
},
{
"property": "pathname",
"operator": "is not",
"value": "/login"
}
]
Filters Example: Only include pageviews/events that occured in the United Kingdom
[
{
"property": "country",
"operator": "is",
"value": "UK"
}
]
Filters Example: Exclude pageviews/events that occured on /register or Desktop
[
{
"property": "pathname",
"operator": "is not",
"value": "/register"
},
{
"property": "device_type",
"operator": "is not",
"value": "Desktop"
}
]

Current Visitors

Returns the total current visitors on the site. Detailed view returns the top 150 pages and top 150 referrers.

Payload Parameters

  • site_id required

    The ID of the site.
    Example: ABCDEFG

  • detailed optional

    Default is false. Set this parameter if you want a detailed breakdown. Otherwise you'll only get a count.

Returns

  • Returns the current visitors.

GET https://api.usefathom.com/v1/current_visitors
curl https://api.usefathom.com/v1/current_visitors \
-H "Authorization: Bearer API_TOKEN_HERE" \
-d site_id=ABCDEFG \
-G
Response
{
"total": 144,
"content": [
{
"pathname": "/spacejam",
"hostname": "https://bugsbunny.com",
"total": 100
},
{
"pathname": "/blog/being-a-wabbit",
"hostname": "https://bugsbunny.com",
"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
}
]
}


If you still have questions or require help with anything, please reach out to us and we'll happily get things sorted out for you.

Pixel cat

Switch to a better Google Analytics alternative

Fathom Analytics is simpler, more accurate and privacy-first. Import your Google Analytics data (UA and GA4), add our single line of code, and watch real-time analytics from your site pour in.

Start a 30-day, unlimited free trial to see how simple analytics can be.

Get started

Check out our full-featured, live demo to see how our software works.

Live demo