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.

Click Create new from the API page.
Give your token a name, and set permissions (Admin, read only (all sites), or site-specific).
Click Save changes.
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.

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.

The rate limits for our API are:

Please note

Query String Parameters

limit optional, default is 10

starting_after optional

ending_before optional

Returns

Returns

Query String Parameters

limit optional, default is 10

starting_after optional

ending_before optional

Returns

URL Parameters

site_id required

Returns

Parameters

name required

sharing optional

share_password optional

Returns

URL Parameters

site_id required

Payload Parameters

name optional

sharing optional

share_password optional

Returns

URL Parameters

site_id required

Returns

URL Parameters

site_id required

Returns

URL Parameters

site_id required

Query String Parameters

limit optional, default is 10

starting_after optional

ending_before optional

Returns

URL Parameters

site_id required

event_id required

Returns

URL Parameters

site_id required

Payload Parameters

name required

Returns

URL Parameters

site_id required

Payload Parameters

name required

Returns

URL Parameters

site_id required

event_id required

Returns

URL Parameters

site_id required

event_id required

Returns

Query String Parameters

entity required

entity_id required

aggregates required

date_grouping optional

field_grouping optional

sort_by optional

timezone optional

date_from optional

date_to optional

limit optional

filters optional

Returns

Payload Parameters

site_id required

detailed optional

Returns