> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mainwp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fathom

> The MainWP Fathom Integration enables you to view Fathom stats for all your Child Sites in your MainWP Dashboard. It adds widgets to both the MainWP overview and individual site overview pages, making it simple to monitor your visitors' data.

## What You'll Learn

* Creating a Fathom API token
* Connecting Fathom to MainWP Dashboard
* Assigning Fathom sites to child sites
* Viewing visitor data and widgets
* Including Fathom data in Pro Reports
* Team Control access for staff users
* Managing Fathom with MainWP Abilities

***

> [!NOTE]
>
> **Integration Add-on** - This add-on extends MainWP to work with Fathom Analytics. It requires a connected Fathom account with sites available to assign in MainWP.

[Fathom - Video Tutorial](https://www.youtube.com/embed/oWxZMmOdy3c)

The Fathom Integration for MainWP simplifies accessing Fathom data for all Child Sites within your MainWP Dashboard. It adds global and individual widgets that display visitor counts and valuable insights, empowering you to make informed decisions for your Child Sites.

## Use This Integration to Track:

* Views
* Users
* Unique pages view
* Average Engagement time
* Visitors by Country
* Visitors by Page
* Visitors by Device
* Views by Referrers
* Visitors by Browsers

## Establishing a connection with a Fathom Account

**1. Navigate to [https://app.usefathom.com/api](https://app.usefathom.com/api)**

Navigate to [https://app.usefathom.com/api](https://app.usefathom.com/api)

**2. Click the Create New button to create an API token**

Click the **Create New** button to create an API token\\

![Fathom API page with Create New button to generate API token](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/fathom-api-create-button.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=c384e4fc6718b5302ef28790abdae05f)

**3. Give the key a name, set Permissions to Admin key, and click the Save change button**

Give the key a name, set **Permissions** to **Admin key,** and click the **Save change** button\\

![Fathom API token creation form with name field and Admin key permission](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/fathom-api-token-form.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=f2df3e9f3111199aa8c541b15fdbe4cb)

**4. Navigate to MainWP Dashboard > Add-ons > Analytics > Fathom > Add Account**

**5. Paste in the API token and click the Connect Account button**

Paste in the API token and click the **Connect Account** button\\

![MainWP Fathom account connection page with API token field and Connect Account button](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/fathom-add-sites-page.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=d8530e836edfd8008833112d42f3a01a)

The Fathom Integration doesn't allow you to insert the Fathom Analytics tracking code on your child sites. To do that, you will need to add the code manually or use a third-party plugin.

## Assigning sites from your Fathom Account to Child Sites in your MainWP Dashboard

**1. Go to MainWP Dashboard > Sites > Manage Sites**

**2. Locate the desired child site and click the Edit action**

Locate the desired child site and click the **Edit** action\\

![Animation showing how to access the Edit action for a child site](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/fathom-edit-site-action.gif?s=b6dda75b56adfef03919cd00e3eb8dde)

**3. Locate the Fathom section**

**4. Select the correct Fathom site from the dropdown menu**

**5. Click the Save Settings button**

Click the **Save Settings** button\\

![Animation showing Fathom site selection and saving settings](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/fathom-site-selection.gif?s=d79002c4d878abbdf30d4a853a04a079)

**6. Repeat the process for all your child sites**

**7. When you are done, you will see those sites in the dropdown on the Add-ons > Analytics > Fathom > Visitor Data page**

When you are done, you will see those sites in the dropdown on the **Add-ons > Analytics > Fathom > Visitor Data** page

## Fathom Visitor Data

After you connect your Fathom Analytics account and assign Fathom sites to your child sites, you will be able to see all Fathom Analytics data on the **Add-ons > Analytics > Fathom > Visitor Data** page.

![Animation showing Fathom Visitor Data page with analytics widgets](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/fathom-visitor-data-page.gif?s=74259335870911636cd4a53f6ca78cf9)

You can disable and enable widgets in [Page Settings](https://docs.mainwp.com/getting-started/mainwp-user-interface.md), and you can re-arrange them in any way you wish.

![Animation showing how to rearrange widgets on the Fathom page](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/fathom-widget-rearrange.gif?s=80700699dbced0e1a91c3c0e2760c31f)

## Refreshing Fathom data

Fathom data is cached in your MainWP Dashboard so that pages load quickly and so the Fathom Aggregation API isn't called on every page view. The cache is refreshed automatically based on the **Data refresh frequency** setting, and you can also refresh it on demand.

### Data refresh frequency

Set how often MainWP fetches fresh stats from your Fathom account:

**1. Go to Add-ons > Analytics > Fathom > Settings**

**2. Choose a value for Data refresh frequency**

Available options are **Every hour**, **Every 3 hours**, **Every 9 hours**, **Every 15 hours**, **Every 18 hours**, and **Every 24 hours**.

**3. Click Save Settings**

> [!TIP]
>
> If you have many connected child sites or are close to your Fathom API rate limit, choose a longer interval. The default cadence is suitable for most installs.

### Refresh Data button

Use the **Refresh Data** button to force an immediate update outside of the configured refresh frequency. It clears the Fathom stats cache and re-fetches data from Fathom for all assigned sites.

* On the **Settings** tab, click the **Refresh Data** button next to **Save Settings**.
* On the **Visitor Data** tab, click the **Refresh Data** button to reload the page with fresh stats.

Use this after assigning new Fathom sites to child sites, or whenever you want to see the latest numbers without waiting for the next scheduled refresh.

Refreshing all sites requires administrator access. [Team Control](#team-control-permissions) staff can refresh only a site they have access to. On the **Visitor Data** tab, they must select that site before they click **Refresh Data**.

## Display interval

The **Display interval** setting on the Settings tab controls the time range shown in Fathom widgets and on the Visitor Data page. Choose **Week** or **Month** depending on the reporting window you want to see by default.

## Removing a connected Fathom account

When you remove a connected Fathom account from MainWP, the add-on automatically clears the Fathom site assignments from your child sites and removes the related cached stats. You don't need to manually clean up child site settings after disconnecting an account.

Removing an account only removes its connection from MainWP. It doesn't delete anything in your Fathom account or remove any child site.

If removal can't finish, MainWP shows **Account removal could not be completed. Click Remove Account to retry.** The account row stays on the page. Click **Remove Account** again to finish the cleanup.

## Widgets

The Fathom widget will be added to the Overview page and on the Individual Child site Overview page.

As always, the widgets can be enabled or disabled in [Page Settings](https://docs.mainwp.com/getting-started/mainwp-user-interface.md), and they can be re-arranged however you wish.

![Fathom widget on the Overview page displaying visitor statistics](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/fathom-overview-widget.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=bf0f2d81ac77c11d37a2284a1dedcc21)

## Fathom data in Pro Reports

Fathom data can be easily included in Pro Reports by selecting it from the Report Data section of the Pro Reports.\\

![Pro Reports Report Data section with Fathom data option selected](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/fathom-pro-reports-data.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=9436c36a599b9828d0298a608af1fde5)

Fathom data can also be included using tokens. You can find a list of all available tokens here: [Available Pro Reports Tokens](https://docs.mainwp.com/add-ons/agency/available-pro-reports-tokens.md)

For more information about Pro Reports and the use of tokens please refer to this KB: [Pro Reports Extension Overview](https://docs.mainwp.com/add-ons/agency/pro-reports-extension-overview.md)

## Team Control permissions

If you use the [Team Control Add-on](https://docs.mainwp.com/add-ons/agency/team-control-extension.md), connecting accounts, removing accounts, and changing **Settings** are limited to administrators. MainWP hides these controls from staff users, and requests to them from staff users have no effect.

Staff users who have the Fathom extension permission can still:

* View and change the Fathom site assignment for child sites they can access
* View Fathom stats on the **Visitor Data** page and in widgets for those sites
* Refresh data for a selected site they can access

The **Visitor Data** page only shows sites the staff user can access. Requests for other sites are denied before MainWP reads cached stats or contacts Fathom.

> [!WARNING]
>
> Team Control staff who could connect accounts, remove accounts, or change Settings in earlier versions lose those controls after the update. An administrator must perform those tasks. There is no separate permission that restores them for staff.

## MainWP Abilities

The Fathom Integration registers abilities in the `mainwp-fathom` category of the [MainWP Abilities API](https://docs.mainwp.com/api-reference/abilities-api/overview.md). Use them to connect accounts, refresh discovered Fathom sites, manage site assignments and settings, read reports and current visitors, refresh cached analytics, and remove account connections from scripts or AI tools.

The abilities, and the Fathom assignment, stats, and overview screens, require a MainWP Dashboard version that includes the Abilities foundation. On older Dashboard versions, those screens deny access. See [Fathom Abilities](https://docs.mainwp.com/api-reference/abilities-api/fathom.md) for inputs, examples, permissions, and errors.

***

## Related Resources

* [Analytics Add-ons](https://docs.mainwp.com/add-ons/analytics.md) - Browse all analytics integrations
* [Pro Reports Extension](https://docs.mainwp.com/add-ons/agency/pro-reports-extension-overview.md) - Include analytics data in reports
* [Available Pro Reports Tokens](https://docs.mainwp.com/add-ons/agency/available-pro-reports-tokens.md) - Fathom tokens
* [Fathom Abilities](https://docs.mainwp.com/api-reference/abilities-api/fathom.md) - Manage Fathom through the Abilities API


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.