Tomtally

API

Read your sites' numbers from your own code: a dashboard, a report, a script. Every call only ever sees the sites of your own account.

Get a key

Sign in, and under Keys on your account page, make a key. Name it after where you'll use it. It is shown once: copy it then. You can revoke it there at any time, and make up to 20.

Send the key in a header with every call:

Authorization: Bearer YOUR_KEY

Never put a key in a web address or in code that runs in a browser: anyone who sees the key can read your numbers. HTTP Basic with the key as the password works too, for tools that only do that.

First call

Your sites, with their events and visitors over the last 30 days:

curl https://tomtally.com/api/v1/sites \
  -H "Authorization: Bearer $TOMTALLY_KEY"

Sign-ups per day on one site this month, with zero for days without any, ready for a chart:

curl -G https://tomtally.com/api/v1/stats \
  -H "Authorization: Bearer $TOMTALLY_KEY" \
  -d site=example.com -d event=signup \
  -d group_by=day -d fill=true -d from=2026-11-01

The same as a spreadsheet: add -d format=csv. In other tools, the parameters go in the address after a ?, as in /api/v1/stats?site=example.com&event=signup; the key still goes in the header.

Endpoints

All are GET and answer in JSON. Each takes from and to (see Stats), except live and health.

AddressWhat it gives
/api/v1/sitesEach of your sites with its id, events, daily unique visitors and the time of its last event. A site with events: 0 probably doesn't have the script yet.
/api/v1/eventsThe event names that occurred, with their counts and the property keys each carries. Start here when you don't know what is being counted.
/api/v1/statsCounts, grouped and filtered the way you ask. Most questions are answered here.
/api/v1/funnelHow many visitors did a series of steps in order on the same day, and what share reached each step. See Funnels.
/api/v1/liveVisitors on each site right now: everyone with an event in the last 5 minutes (minutes changes that, up to 30). Someone reading a page counts too, see heartbeat. Takes no dates.
/api/v1/healthWhether one of your sites went silent: at least 20 events in the week before, and none in the last 24 hours. Usually a sign its script broke.

The full machine-readable description is at /api/v1/openapi.json (OpenAPI 3).

Stats

GET /api/v1/stats with any of these:

ParameterDefaultMeaning
from, tolast 30 daysFirst and last day, both included, as 2026-11-01. Days are calendar days in Amsterdam time. At most 10 years.
group_bysite,eventComma-separated: at most one of day, week, month, plus any of site, host, event, path, and up to 3 properties as prop.plan. Empty (group_by=) gives one total.
site, host, event, pathOnly this exact value. site includes its subdomains; host is one exact hostname.
path_prefixOnly paths that start with this, such as /blog/
prop.<key>Only events with this property value, such as prop.plan=pro. Up to 5.
fillfalseWith day, week or month: adds rows with 0 for periods without events. Use it for charts.
include_suspectfalseAlso count events that look like they came from a bot
limit1000The most rows, up to 10000
coarsentrueWhen a time series has more rows than limit, group it by week or month instead, if that fits
formatjsoncsv for a spreadsheet

An answer looks like this (shortened):

{
  "from": "2026-11-01",
  "to": "2026-11-16",
  "timezone": "Europe/Amsterdam",
  "group_by": ["day"],
  "total_events": 41,
  "total_uniques": 38,
  "truncated": false,
  "coarsened": false,
  "note": null,
  "rows": [
    { "day": "2026-11-15", "events": 0, "uniques": 0,
      "last_at": null },
    { "day": "2026-11-16", "events": 3, "uniques": 3,
      "last_at": "2026-11-16T14:02:11.000Z" }
  ]
}

Rows by day, week or month come oldest first; otherwise the largest groups come first.

When note isn't null, read it: it says when rows were grouped more coarsely than you asked (coarsened) or left out to stay within limit (truncated). total_events always counts everything. Rows also carry clicks, the old name of events: use events.

Funnels

GET /api/v1/funnel counts how many visitors did a series of steps in this order, and what share of them made it to each step. Give 2 to 5 steps as step1, step2 and so on, each an event name. A step can also take a page (step2.path or step2.path_prefix) and up to 3 properties (step2.prop.plan=pro). For the whole funnel there are site, host, from, to and include_suspect, and group_by (one of day, week or month, and/or site) with fill=true for a chart.

From the home page to a sign-up, on one site:

curl -G https://tomtally.com/api/v1/funnel \
  -H "Authorization: Bearer $TOMTALLY_KEY" \
  -d site=example.com -d step1=screen_view -d step1.path=/ \
  -d step2=signup_click -d step3=signup

Each step in steps has visitors, of_first (its share of step 1) and of_previous (its share of the step before). A visitor is counted once per day: Tomtally recognises a visitor for one day only, so a funnel follows what someone did on one day, and someone who signs up the day after their first visit starts again at step 1. That is what makes these shares conversion rates you can rely on, which daily unique visitors from stats can't give. A step counts when it happened after the step before, or at the same moment; doing it only earlier that day doesn't count. When two steps have the same event name, the later one must come strictly after, so two screen_view steps mean two page views.

What the numbers mean

Limits and errors

Your account can make 60 calls a minute, counting the API, Claude and your account page together. The same question asked again within a minute gets the same answer (it still counts as a call); generated_at says when the numbers were counted. Errors come back as JSON with an error that says what to change.

StatusMeans
400A parameter is wrong, or the question would read too much data. The message says which; narrow the range or the filters.
401The key is missing, mistyped or revoked
429More than 60 calls in a minute. Wait for the number of seconds in Retry-After.
503Briefly unavailable. Try again in a minute.

With Claude

Claude can read the same numbers without a key, and answer in plain words or build a dashboard. In claude.ai, the desktop app or on your phone, connect it from Claude's connector directory (or add https://tomtally.com/mcp as a custom connector) and sign in. In Claude Code:

claude mcp add --transport http tomtally https://tomtally.com/mcp

then /mcp to sign in. You'll see the connection on your account page, where you can disconnect it.