@kody/fathom-analyticsFork

@kody/fathom-analytics

Intent

Give agents a simple, documented way to read Fathom Analytics data — site stats, ad-hoc aggregation reports, current visitors, and briefing-ready traffic summaries — without hand-writing authenticated fetch calls each time.

What it does

• Verify API access and list readable sites (smokeTest, listSites)
• Pull traffic numbers for a site: totals, top pages, top referrers (getSiteTrafficSummary)
• Run flexible aggregation reports over pageviews or custom events (aggregate)
• Check who is on a site right now (getCurrentVisitors)
• Reach any other Fathom endpoint through the guarded raw request helper

Prerequisites / setup

1. Create an API token at https://app.usefathom.com/api
2. Save it as a user secret named FATHOM_ANALYTICS_API_TOKEN (do not paste the value in chat):

https://kody.codes/account/secrets/new?name=FATHOM_ANALYTICS_API_TOKEN&description=Fathom%20Analytics%20API%20token&allowedHosts=api.usefathom.com&scope=user

3. Approve host api.usefathom.com in the account secrets UI
4. Agents: see AGENTS.md for import paths, smoke checks, and call-cost notes

Every API request counts as one pageview against the Fathom plan. Keep call counts low (getSiteTrafficSummary = 3 requests, smokeTest = 2). Free-tier rate limits are about 600 requests/hour and 5 concurrent.

This package deliberately ships no mutation helpers (create/update/delete sites, events, milestones). Use the raw request helper only when you explicitly ask for a write.

Done when

• FATHOM_ANALYTICS_API_TOKEN is saved and api.usefathom.com is approved
• Smoke test returns token metadata plus a site list
• Traffic summaries and aggregations return expected windows for a known site

Branding

The community icon is the official Fathom Analytics mark, used with explicit permission from Fathom co-founder Jack Ellis: https://x.com/JackEllis/status/2081959336176185404 ("Yes you can! :D", 2026-07-28). Fathom Analytics is a product of Conva Ventures Inc.; this package is not affiliated with or endorsed by them.

Docs

• Fathom Analytics API v1