Mattering Automations GoatCounter integration
Connect GoatCounter to Mattering Automations: total pageviews, top pages, per-page referrers, the dashboard breakdowns with drill-down, the path catalog, sites, raw exports and server-side pageview counting as workflow steps, authenticated with one site code and one API token.
The Mattering Automations GoatCounter integration puts GoatCounter API v0 on your automation canvas: total pageviews with the per-day series behind them, top pages, per-page referrers, the six dashboard breakdowns with drill-down, the path catalog, site reads and provisioning, background exports of raw pageview rows, and server-side pageview counting for things that never render a page. All 15 nodes together are complete coverage of GoatCounter's documented API.
The credential holds two values that belong together: a site code and an API token, sent as an Authorization Bearer header. GoatCounter addresses each site by its own subdomain and mints a token inside one site rather than at the account level, and its reporting endpoints carry no site parameter at all, so the host is what decides which site you are reading. That is why both values live on the credential and why a second site means a second credential. Self-hosting is fully supported: put your instance's https base URL in the same field.
One thing is worth reading before you create the token, because it causes more confusion here than anything else. GoatCounter tokens carry per-route permission checkboxes, and a missing permission answers 403 rather than 401. Only one route is permission-free, and it is the one Test Connection uses, so a token with nothing ticked passes the test and then fails on every other node. The credential walkthrough below says which permission each node family needs.
Before you start
- A GoatCounter site you can sign in to, hosted on goatcounter.com or self-hosted. The token is created inside that site under User then API.
- Your site code to hand. It is the subdomain of your dashboard, so example for https://example.goatcounter.com. Self-hosting instead? You need your full https base URL, for example https://stats.example.com. Plain http is refused rather than upgraded, because it would put the token on the wire in the clear.
- A decision about which node families you need, because GoatCounter gates by TOKEN PERMISSION rather than by plan. There are no paid feature tiers to check here: what a node can do depends entirely on which checkboxes were ticked when the token was made. Reporting and the path catalog need statistics, the site readers need site read, GoatCounter: Create Site needs site create, GoatCounter: Update Site needs site update, the export family needs export, and GoatCounter: Send Pageviews needs count.
- One credential per site you want to report on. GoatCounter's stats endpoints follow the credential's own host and take no site parameter, so listing sites does not let you report on them.
- A Mattering workspace with access to the Automations app.
- Worth knowing before you plan volume: GoatCounter's own wording is that goatcounter.com is currently offered for free for reasonable public usage. The vendor names sending millions of pageviews a day as outside that, publishes no quota and no service level agreement, and recommends self-hosting for more serious purposes. This integration works the same either way.
Create a GoatCounter API token
GoatCounter tokens are made inside a site, not at the account level, and each one carries a set of permission checkboxes that decide which routes it may call. Tick them deliberately: this is the single most common cause of a credential that tests fine and then fails in a workflow.
Connect GoatCounter to Mattering
Verify it works
Open any automation canvas and check the palette: a GoatCounter section should list the read and action nodes. Drop GoatCounter: Get Current User onto the canvas and run a test step first. It needs no parameters and no permission, and it returns your account plus the token's own permission bits, so it is both the health check and the answer to any 403 you meet later.
Now prove a permission actually works, because the first step deliberately does not. Drop GoatCounter: Get Total Pageviews onto the canvas, set a start and an end covering the last seven days, and run it. A successful response carries the range total, the events-only total, a UTC-aligned total, and one row per day. If this returns 403 while the first step returned 200, the token is missing the statistics permission rather than being invalid.
Finally, check the ids that everything else filters on. Drop GoatCounter: List Paths onto the canvas and run it: it returns every path and event recorded for this site with its numeric id, which is the value GoatCounter: Get Path Referrers needs. Everything in this verify path is read-only, so it cannot touch the two irreversible nodes and is safe to re-run whenever you rotate the token.
Node reference
15 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 11
GoatCounter: Download Export
goatcounter_download_export
Download a finished export's file. GoatCounter serves it gzip-compressed; this node decompresses it and returns the text at data.content, with data.format, data.bytes and data.truncated alongside. Exports of a busy site are large, so the text is capped and data.truncated says whether it was cut, which makes this suitable for a small site's full history or for an incremental export started with start_from_hit_id, and not for pulling millions of rows through a workflow. Check GoatCounter: Get Export first: downloading before finished_at is set returns an error rather than a partial file. Needs the export permission.
GoatCounter: Get Breakdown Detail
goatcounter_get_stat_detail
Drill into one row of a breakdown: pick Firefox from browsers and get its versions, pick a country from locations and get its regions, pick a campaign and get its sources. Same response shape as the breakdown node, one level deeper. Supports browsers, systems, locations, campaigns, toprefs and sizes; languages has no detail view. Needs the statistics permission.
GoatCounter: Get Breakdown Stats
goatcounter_get_stats
One of GoatCounter's dashboard breakdowns for a date range: browsers, systems, locations, languages, campaigns, toprefs or sizes. Returns data.stats as one row per value with an id, a human-readable name and a count, ordered by count descending, plus data.more. Pick the breakdown with the page field. Needs the statistics permission.
GoatCounter: Get Current User
goatcounter_get_me
Get the account behind the stored API key, plus the key's own permissions: data.user carries the email, settings and timezone, and data.token carries the key name and its permission bits. Takes no parameters and needs no permission bit of its own, which makes it the connector's credential health check and the first call to run when another node returns 403.
GoatCounter: Get Export
goatcounter_get_export
Check on an export started with GoatCounter: Start Export. The job is finished when data.finished_at is set and data.error is null; the response also carries the row count, the file size, a SHA256 hash of the file, and the last_hit_id to use as the next run's cursor. Poll this before downloading. Needs the export permission.
GoatCounter: Get Pageviews By Path
goatcounter_get_hits
Top pages for a date range: data.hits is one row per path with its total count, title, whether it is an event, and a nested per-day series at hits[].stats carrying daily, weekly, monthly and hourly values. This is the closest thing GoatCounter has to its dashboard's main table. Rows are ordered by count descending and cut off at limit, so the result is a TOP N and not the whole site unless data.more is false. Needs the statistics permission.
GoatCounter: Get Path Referrers
goatcounter_get_path_refs
Where the traffic to ONE page came from: data.refs is one row per referrer with its name and count, ordered by count descending, plus a ref_scheme telling you whether it was a link, a search engine, a campaign or something else. Offset paginated, so unlike the other stat listers this one can be walked to completion. Needs the statistics permission. Rate limit note: fanning this out across many paths is the easiest way to trip GoatCounter's 4 requests per second cap.
GoatCounter: Get Site
goatcounter_get_site
Fetch one site by numeric id: code, custom domain, link domain, state, whether it has ever received data, and its full settings object including the data retention window. Needs the site read permission. Field-name trap, and this is the wire format rather than a mistake in this description: a site's settings come back under the key setttings, with three t's, because that is the JSON tag GoatCounter ships. Read data.setttings; data.settings resolves to nothing.
GoatCounter: Get Total Pageviews
goatcounter_get_total_stats
Total counts for a date range, plus the per-day series behind them: data.total for everything, data.total_events for events only, data.total_utc for the same total computed over UTC days instead of the site's timezone, and data.stats as one row per day carrying that day's number and a 24-slot hourly array. This is the node to hang a traffic chart on. Needs the statistics permission.
GoatCounter: List Paths
goatcounter_list_paths
List every path and event GoatCounter has recorded for this site, at data.paths, with no statistics attached: id, path, title, and whether it is an event rather than a pageview. These ids are what the stats nodes filter on, so this is the node that turns a URL into something the reporting endpoints accept. Cursor-paginated with after; data.more says whether another page exists. Needs the statistics permission.
GoatCounter: List Sites
goatcounter_list_sites
List the site this API key belongs to and every child site created under it, at data.sites, each with its numeric id, code (the subdomain), custom domain, link domain and settings. Needs the site read permission. Note this does not switch which site the stats nodes report on: those always follow the credential's own site code, so reporting on a child site means storing a second credential. Field-name trap, and this is the wire format rather than a mistake in this description: a site's settings come back under the key setttings, with three t's, because that is the JSON tag GoatCounter ships. Read data.setttings; data.settings resolves to nothing.
Action nodes 4
GoatCounter: Create Site
goatcounter_create_site
Create a new site as a CHILD of the site this API key belongs to, which is how one GoatCounter account tracks several domains. The code becomes the new site's subdomain and must be globally unique across GoatCounter. Needs the site create permission. Reversible, but not from here: GoatCounter ships no delete-site API endpoint, so removing a site is done in its web interface under Settings.
GoatCounter: Send Pageviews
goatcounter_count_pageviews
Record pageviews or events server-side, without a browser and without the tracking script: useful for counting API hits, downloads, emails opened, or anything that never renders a page. Send up to a few hundred hits per call, each with at least a path. Needs the count permission. IRREVERSIBLE: GoatCounter has no endpoint that deletes pageviews, and created_at can write into periods you have already reported on, so a mistake here permanently changes the site's numbers and can only be undone from GoatCounter's own purge screen. Point it at a test site first.
GoatCounter: Start Export
goatcounter_create_export
Start a background export of this site's raw pageviews, which is the only way to get row-level data out of GoatCounter (the stats endpoints only ever return aggregates). Returns immediately with the export's id and its last_hit_id; the file is not ready yet. Poll GoatCounter: Get Export until finished_at is set, then fetch it with GoatCounter: Download Export. Keep last_hit_id and pass it back as start_from_hit_id next time to export only what is new. Needs the export permission. Creates a file on GoatCounter's side and changes no analytics data.
GoatCounter: Update Site
goatcounter_update_site
Update a site's settings, custom domain or link domain. Needs the site update permission. Two warnings, both irreversible. First, settings is a WHOLE-OBJECT REPLACE: keys you leave out are reset rather than kept, so read the site first and send the complete object back with your change applied. Second, settings.data_retention permanently deletes every pageview older than that many days, with no undo and no API route that could restore them. Request bodies spell the key settings; responses spell it setttings with three t's.
Using the integration
On the automation canvas
GoatCounter nodes chain with every other node. A weekly schedule can run GoatCounter: Get Total Pageviews and write the row into a Mattering database so a history builds itself, GoatCounter: Get Pageviews By Path can feed a condition that only opens a task when a page moves further than it should have, and GoatCounter: Get Path Referrers can explain the page that moved. Two values do most of the wiring: the date range, which every reporting node takes as an explicit start and end because GoatCounter has no API-side presets, and the path id from GoatCounter: List Paths, which is what the referrer node filters on. Note there is no trigger here: GoatCounter publishes no webhooks and no alerting endpoint, so anything that watches for a change is a scheduled poll rather than a subscription.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. An agent can answer which pages grew this month with GoatCounter: Get Pageviews By Path over two windows, follow it with GoatCounter: Get Path Referrers on the page that changed, and check a browser or country split with GoatCounter: Get Breakdown Stats. GoatCounter publishes no MCP server of its own as of August 2026, so there is no vendor tool to weigh this against; what this integration adds over a chat session is that the same nodes run on a schedule with nobody present, chain with every other connector in one workflow, and hold the credential once in a shared workspace. Keep agents on the eleven read nodes, and gate the two irreversible ones.
One site per credential, and self-hosting
This is the wrinkle worth ten seconds of attention. GoatCounter's reporting endpoints take no site parameter: GoatCounter: Get Total Pageviews, GoatCounter: Get Pageviews By Path, GoatCounter: Get Path Referrers, GoatCounter: Get Breakdown Stats and GoatCounter: List Paths all report on whichever site the HOST resolved to, and the host comes from the credential's site code. So one credential is one site, and a second site needs a second credential. GoatCounter: List Sites will still show the site your key belongs to plus any child sites created under it, and GoatCounter: Create Site can add one, but neither changes which site the reporting nodes read. The same field carries a self-hosted instance: enter https://stats.example.com rather than a bare code and everything else behaves identically. The connector normalizes what you paste, so a bare hostname, a trailing slash or a copied API path all resolve to the same origin, while plain http is refused outright rather than silently upgraded.
Reading the numbers correctly
Three properties of GoatCounter's reporting decide whether a dashboard built on it is right. First, GoatCounter: Get Pageviews By Path is ranked and truncated: rows come back ordered by count and cut off at your limit, so it answers top N rather than everything unless the response says there is nothing more. Second, GoatCounter: Get Path Referrers is the one stat reader that is offset paginated, so it can be walked to completion, which is why it is the right node when a total actually has to be complete. Third, the start and end you pass are in the SITE's timezone rather than UTC, which is exactly why GoatCounter: Get Total Pageviews returns a separate UTC-aligned figure beside the ordinary one. Compare like with like when GoatCounter is going next to a UTC-based source, or the two will disagree at the day boundaries. Everything GoatCounter returns is a count. There is no rate, percentage or bounce figure anywhere in this API.
The breakdowns and their drill-down
GoatCounter: Get Breakdown Stats serves the dashboard's dimension tables for a date range, chosen with a page field: browsers, systems, locations, languages, campaigns, top referrers, or screen sizes. Each row carries an id, a readable name and a count. GoatCounter: Get Breakdown Detail takes one of those rows and goes a level deeper, so a browser becomes its versions, a country becomes its regions, and a campaign becomes its sources. The detail form supports the same set MINUS languages: GoatCounter has no per-language breakdown, and the node says so. On the canvas the detail node's picker is dependent, so choose the breakdown first and the row list fills from the breakdown you chose.
Getting raw rows out with an incremental cursor
The stats endpoints only ever return aggregates, so row-level data comes out of the export family, and it is a three-step asynchronous shape. GoatCounter: Start Export begins the job and returns immediately with an export id and a last_hit_id; the file is not ready yet. GoatCounter: Get Export is polled until the job reports a finish time with no error, and it also returns the row count, the file size and a hash. GoatCounter: Download Export then fetches and decompresses it. Two things to build around. Downloading before the job finishes returns an error rather than a partial file, so always poll first. And an export is a whole-dataset dump by default, which is not something to pull through a workflow for a busy site: keep the last_hit_id from each run and pass it back as the next run's starting point so each export carries only what is new. The download node caps what it pulls into a node output and reports honestly whether it was cut. There is no list-exports endpoint in this API, so an export id only ever comes from the node that started it.
Server-side counting, and why it is flagged
GoatCounter: Send Pageviews records hits without a browser and without the tracking script, which is the node for counting API calls, downloads, or emails opened. It is irreversible and the flag is not decoration: GoatCounter publishes no endpoint that deletes pageviews, and the node accepts a created_at in the past, so a mistake permanently changes a period you have already reported on and can only be undone from GoatCounter's own purge screen. Point it at a throwaway site before it goes anywhere near a real one. There is a subtler failure too. GoatCounter deliberately REJECTS a hit that carries neither a session nor both a user agent and an IP address. Turning that guard off accepts them, but from a server every hit then looks like it came from the same origin, so visitor numbers stop meaning what they meant unless you supply your own session value. One more silent case: hits dropped by GoatCounter's IP filter are reported in a response HEADER rather than in the body, so a workflow cannot tell from the data that anything was dropped.
Sites, and the settings key with three t's
GoatCounter: List Sites returns the site this key belongs to plus any child sites created under it, GoatCounter: Get Site fetches one by id, GoatCounter: Create Site adds a child site (the code becomes its subdomain and must be globally unique across GoatCounter), and GoatCounter: Update Site changes settings, custom domain or link domain. Two things will bite a read-modify-write workflow here if nobody warns you. First, a site's settings come back under a key spelled with THREE t's, because that is the JSON tag GoatCounter ships, while the update REQUEST body spells the same key with two. So you read one spelling and write the other, and a path using the correct-looking spelling on a read resolves to nothing at all. Second, the settings field on the update is a WHOLE-OBJECT REPLACE rather than a merge: keys you leave out are reset, not kept. Read the site first, apply your change to the complete object, and send it all back. The data retention setting inside it permanently deletes every pageview older than the window you set, with no undo and no API route that could restore them, which is why the update node is flagged irreversible. GoatCounter ships no delete-site endpoint at all, so removing a site is done in its own web interface.
Troubleshooting
Test Connection passes but every other node returns 403
Test Connection fails with a 401
A reporting node returns nothing for a site I know has traffic
A path expression reading a site's settings resolves to nothing
Update Site reset settings I did not touch
A workflow starts failing part way through with 429 responses
Download Export returns an error instead of a file
The top pages list does not add up to the site total
Send Pageviews recorded traffic that looks like one visitor
Related
The GoatCounter MCP
What connecting GoatCounter unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
GoatCounter is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.