{"openapi":"3.1.0","info":{"title":"Fathom Analytics (BYOK) API","version":"0.1.0","description":"Fathom Analytics (BYOK) lets an AI assistant read your own Fathom Analytics data through the Fathom Analytics API with a key you supply (Fathom Analytics API token). Read-only: 7 tools (get_account, get_token_info, list_sites, get_site, list_site_events, get_current_visitors, get_aggregation). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-fathomanalytics.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-fathomanalytics/docs"},"termsOfService":"https://connectorbay.com/byok-fathomanalytics/terms"},"servers":[{"url":"https://byok-fathomanalytics.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-fathomanalytics/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_account":{"post":{"operationId":"get_account","summary":"Show the Fathom Analytics account the token belongs to: id, name and email. Each Fathom API call counts toward the accou","description":"Show the Fathom Analytics account the token belongs to: id, name and email. Each Fathom API call counts toward the account's monthly pageview quota. Use for \"Which Fathom Analytics account is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_accountArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_token_info":{"post":{"operationId":"get_token_info","summary":"Show details of the API token in use: name, abilities, last use and expiry. Each Fathom API call counts toward the accou","description":"Show details of the API token in use: name, abilities, last use and expiry. Each Fathom API call counts toward the account's monthly pageview quota. Use for \"What can my Fathom API token do and when does it expire\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_token_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_sites":{"post":{"operationId":"list_sites","summary":"List the Fathom sites with id, name, sharing setting, time zone and creation time; cursor-paged. Each Fathom API call co","description":"List the Fathom sites with id, name, sharing setting, time zone and creation time; cursor-paged. Each Fathom API call counts toward the account's monthly pageview quota. Use for \"Which sites do I track with Fathom Analytics\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Records to return (1 to 100, default 10).","title":"Limit"},"starting_after":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor: the id of the last item of the previous page; leave out for the first page.","title":"Starting After"}},"title":"list_sitesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_site":{"post":{"operationId":"get_site","summary":"Get one Fathom site by id: name, sharing setting, time zone and creation time. Each Fathom API call counts toward the ac","description":"Get one Fathom site by id: name, sharing setting, time zone and creation time. Each Fathom API call counts toward the account's monthly pageview quota. Use for \"Show the Fathom site CDBUGS\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Site id (the id field from list_sites), for example 'CDBUGS'.","maxLength":30,"title":"Site Id","type":"string"}},"required":["site_id"],"title":"get_siteArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_site_events":{"post":{"operationId":"list_site_events","summary":"List the event (goal) definitions of a Fathom site by name and currency; cursor-paged. Each Fathom API call counts towar","description":"List the event (goal) definitions of a Fathom site by name and currency; cursor-paged. Each Fathom API call counts toward the account's monthly pageview quota. Use for \"Which conversion events are defined on my Fathom site\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Site id (the id field from list_sites), for example 'CDBUGS'.","maxLength":30,"title":"Site Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Records to return (1 to 100, default 10).","title":"Limit"},"starting_after":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor: the id of the last item of the previous page; leave out for the first page.","title":"Starting After"}},"required":["site_id"],"title":"list_site_eventsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_current_visitors":{"post":{"operationId":"get_current_visitors","summary":"Show how many visitors a Fathom site has right now, optionally with the pages they view and where they came from. Each F","description":"Show how many visitors a Fathom site has right now, optionally with the pages they view and where they came from. Each Fathom API call counts toward the account's monthly pageview quota. Use for \"How many visitors are on my Fathom site right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Site id from list_sites.","maxLength":30,"title":"Site Id","type":"string"},"detailed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include current pages and referrers.","title":"Detailed"}},"required":["site_id"],"title":"get_current_visitorsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_aggregation":{"post":{"operationId":"get_aggregation","summary":"Run a Fathom aggregation report. For pageviews give entity pageview, the site id as entity_id and aggregates such as pag","description":"Run a Fathom aggregation report. For pageviews give entity pageview, the site id as entity_id and aggregates such as pageviews, visits, uniques, avg_duration or bounce_rate; for conversions give entity event, site_id, entity_name and aggregates conversions, unique_conversions or value. Group by date and/or fields such as pathname, referrer_hostname, browser, country_code or device_type. Numbers come back as strings. Hourly grouping only works for ranges up to 7 days. Each Fathom API call counts toward the account's monthly pageview quota. Use for \"How many pageviews did my Fathom site get per day last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"entity":{"description":"What to aggregate: pageview or event.","enum":["pageview","event"],"title":"Entity","type":"string"},"aggregates":{"description":"Comma-separated metrics. Pageview: visits, uniques, pageviews, avg_duration, bounce_rate. Event: conversions, unique_conversions, value.","maxLength":200,"title":"Aggregates","type":"string"},"entity_id":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Site id; required when entity is pageview.","title":"Entity Id"},"site_id":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Site id; required when entity is event and entity_id is not given.","title":"Site Id"},"entity_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Event name; required when entity is event and entity_id is not given.","title":"Entity Name"},"date_grouping":{"anyOf":[{"enum":["hour","day","month","year"],"type":"string"},{"type":"null"}],"default":null,"description":"Group results by hour, day, month or year.","title":"Date Grouping"},"field_grouping":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated fields to group by, for example 'pathname' or 'browser,device_type'. Others include hostname, referrer_hostname, referrer_source, country_code, city, operating_system, utm_source, utm_medium, utm_campaign.","title":"Field Grouping"},"sort_by":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort as field:asc or field:desc, for example 'pageviews:desc'; use timestamp:asc or timestamp:desc with date_grouping.","title":"Sort By"},"date_from":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start time, for example 2026-10-01 00:00:00, in the timezone you report in. Default: first recorded data.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End time, for example 2026-10-07 23:59:59. Default: now.","title":"Date To"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Rows to return (1 to 1000; 500 when grouping by fields and not set).","title":"Limit"}},"required":["entity","aggregates"],"title":"get_aggregationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}