Skip to content
← Public packages

@kody/fathom-analytics

Read Fathom Analytics site stats, aggregation reports, and current visitors.

README.md

55 lines · 2.1 KB · Markdown

@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

  1. Approve host api.usefathom.com in the account secrets UI
  2. 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