@kody/fathom-analytics

@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.

When to use

• Verify Fathom 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

Required setup

• FATHOM_ANALYTICS_API_TOKEN secret (user scope) sent as the Authorization: Bearer header on every request. Create an API token at https://app.usefathom.com/api, then save it as a secret.
• Prefill: https://heykody.dev/account/secrets/new?name=FATHOM_ANALYTICS_API_TOKEN&description=Fathom%20Analytics%20API%20token&allowedHosts=api.usefathom.com&scope=user

Exports

• kody:@kody/fathom-analytics — action dispatcher plus named helpers (request, getAccount, getToken, listSites, getSite, listEvents, getEvent, aggregate, getCurrentVisitors, getSiteTrafficSummary, smokeTest)

Examples

import fathom from 'kody:@kody/fathom-analytics'

export default async function main() {
	// Discover sites, then get a 7-day briefing-ready summary for one.
	const access = await fathom({ action: 'smokeTest' })
	return await fathom({
		action: 'getSiteTrafficSummary',
		siteId: 'CDBUGS',
		days: 7,
	})
}

import { aggregate } from 'kody:@kody/fathom-analytics'

export default async function main() {
	// Top blog posts by pageviews this month.
	return await aggregate({
		siteId: 'CDBUGS',
		aggregates: 'pageviews,uniques',
		fieldGrouping: 'pathname',
		sortBy: 'pageviews:desc',
		limit: 20,
		dateFrom: '2026-07-01 00:00:00',
		filters: [{ property: 'pathname', operator: 'is like', value: '/blog/*' }],
	})
}

Notes

• Every API request counts as one pageview against the Fathom plan. Keep call counts low; getSiteTrafficSummary costs 3 requests, smokeTest costs 2.
• Rate limits are per account (free tier: 600 requests/hour, 5 concurrent). The request helper retries 429/5xx automatically honoring Retry-After.
• Aggregation responses return numeric values as strings; getSiteTrafficSummary converts them to numbers.
• Aggregation data is only accurate from March 2021 onwards, and date_from/date_to timestamps are interpreted in the site's reporting timezone.
• The API also supports mutations (create/update/delete sites, events, milestones). This package deliberately ships no mutation helpers — use the raw request helper for those, and only when the user explicitly asks.
• List helpers default to limit: 100 (the API maximum) and surface hasMore plus the raw list response for cursor pagination via startingAfter / endingBefore.
• Full API reference: https://usefathom.com/api/v1

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.