API reference
Browse API documentation
API reference

Sites

Create and manage the sites in your Fathom account.

List sites#

GET/sites

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

Query parameters

limitintegeroptional
A limit on the number of objects to be returned, between 1 and 100.
Default 10
starting_afterstringoptional
A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For example, if you make a list request and receive 10 objects ending with obj_foo, your subsequent call can include starting_after=obj_foo to fetch the next page.
ending_beforestringoptional
A cursor for use in pagination, working in the opposite direction to starting_after. ending_before is an object ID that defines your place in the list.

Returns

A list of site objects.

GET
curl "https://api.usefathom.com/v1/sites" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
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",
            "timezone": "America/New_York"
        }
    ]
}

Get site#

GET/sites/{site_id}

Return a single site.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Returns

A site object.

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

Create site#

POST/sites

Create a site.

Body parameters

namestringrequired
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
sharingstringoptional
The sharing configuration. Supported values are none, private or public.
Default noneOptionsnoneprivatepublic
share_passwordstringRequired if sharing is private
When sharing is set to private, you must also send a password to access the site with (up to 255 characters).
timezonestringoptional
The site's reporting timezone as a TZ database name (e.g. America/New_York). If omitted, the site inherits your account's default timezone.
multi_domainbooleanoptional
Set to true to allow this site to track multiple domains.
Default false
multi_domain_optionstringRequired if multi_domain is true
How multi-domain data is grouped. Supported values are combined (report all domains together) or separate (report each domain individually).
Optionscombinedseparate

Returns

A site object.

POST
curl -X POST "https://api.usefathom.com/v1/sites" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Bugs Bunny Portfolio"
  }'
Response
{
    "id": "GCDFS",
    "object": "site",
    "name": "Acme Inc",
    "sharing": "none",
    "created_at": "2021-08-10 00:45:43",
    "timezone": "America/New_York"
}

Update site#

POST/sites/{site_id}

Update a site. Send only the fields you want to change.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Body parameters

namestringoptional
The name of the website (up to 255 characters).
sharingstringoptional
The sharing configuration. Supported values are none, private or public.
Optionsnoneprivatepublic
share_passwordstringRequired if sharing is private
When sharing is set to private, you must also send a password to access the site with (up to 255 characters).
timezonestringoptional
The site's reporting timezone as a TZ database name (e.g. America/New_York). Reporting for this site will use this timezone.
multi_domainbooleanoptional
Set to true to allow this site to track multiple domains.
multi_domain_optionstringRequired if multi_domain is true
How multi-domain data is grouped: combined or separate.
Optionscombinedseparate

Returns

A site object.

POST
curl -X POST "https://api.usefathom.com/v1/sites/CDBUGS" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Response
{
    "id": "GCDFS",
    "object": "site",
    "name": "Acme Holdings Inc",
    "sharing": "private",
    "created_at": "2021-08-10 00:45:43",
    "timezone": "America/New_York"
}

Wipe site#

Deprecated

DELETE/sites/{site_id}/data

This endpoint is no longer available

This endpoint has been retired and now returns 410 Gone. It is no longer possible to wipe a site's data via the API.

Previously wiped all pageviews and event completions from a website. This endpoint is no longer available.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Delete site#

DELETE/sites/{site_id}

Delete a site. Careful: you can't undo this, and neither can we.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Returns

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

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