ReaderCount API

ReaderCount API and AI connector.

Read your stats from your own code, dashboards and spreadsheets, or ask Claude about them in plain English. The API only reads, so nothing it does can change your stats.

Back to ReaderCount Every API

1Get started

The API lives on your own ReaderCount, at your stats address:

https://stats.yourdomain.co.uk/api/v1

Open API keysOpen your stats page for the website and go to API.
Make a keyGive it a name and copy it. It's shown once, and starts with rc_.
Send it with each requestIn an Authorization header, like this:

curl "https://stats.yourdomain.co.uk/api/v1/overview?period=7d" \
  -H "Authorization: Bearer rc_••••••••••••••••••••••••••••••••"

2Keys

Each key reads one website and can't change anything. A website can have up to 10 keys, so make one for each script, and delete any you no longer use. Removing a website stops its keys too.

Keep keys on your server. There are no browser (CORS) headers on purpose, because a key in a web page can be copied by anyone. A key put in the web address is refused for the same reason.

3Every request

Request	What it gives
`GET /overview`	Headline stats for a period with the period before: visitors, page views, time on page, bounce rate, people on the site now, top pages, sources, countries, devices and clicks. Takes `period`.
`GET /breakdown`	Views or clicks grouped by one thing. Takes `of` (`views` or `clicks`), `by` (`page`, `source`, `campaign`, `country`, `device`, `browser`, `day`, `link` and more), `period` or `from` and `to`, filters such as `page`, `source`, `country` and `link_contains`, and `limit`.
`GET /google-searches`	Google Search Console figures, when connected: searches, clicks, impressions and position. Takes `by` (`query`, `page` or `day`), `query_contains`, `sort` and `limit`.
`GET /check`	Whether the website's visits are arriving, the same as the stats page's set-up check.

Dates are YYYY-MM-DD in UTC. Visitors are counted per day, so the same person on two days counts twice.

4Examples

Top pages from Google this month

curl "https://stats.yourdomain.co.uk/api/v1/breakdown?by=page&source=Google&period=30d" \
  -H "Authorization: Bearer $RC_KEY"

In JavaScript

const res = await fetch(`${RC_API_URL}/overview?period=7d`, {
  headers: { Authorization: `Bearer ${process.env.RC_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error);
const stats = await res.json();

5Webhooks

ReaderCount doesn't send webhooks. It emails you a weekly summary and alerts instead, which you can switch on from your stats page.

6AI connector

ReaderCount has a Claude connector built in. In Claude, open Settings › Connectors › Add custom connector and paste:

https://stats.yourdomain.co.uk/mcp

Claude asks you to sign in to ReaderCount once. Then ask things like “which posts brought in the most readers from Google last month?”. Claude can only read your stats, and Disconnect on your stats page signs it out.

7Errors and limits

Anything that goes wrong comes back with a status, a sentence you can show to a person and a link to the docs:

{"error": "That API key isn't right, or it has been deleted.", "docs": "https://github.com/pobren/readercount#api"}

Status	What it means
`400`	Something in the request needs fixing, such as a key put in the web address.
`401`	No key, or a key that has been deleted.
`404`	A request the API doesn't have. The error lists the ones it does.
`405`	The API only reads, so every request is a `GET`.
`429`	Each key can make 60 requests a minute. `Retry-After` says how long to wait.

Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining, so you can slow down before you hit the limit.

Questions or ideas? Ask in GitHub Discussions, or open an issue for a bug.

Stay in the loop

Subscribe for updates.

Leave your email and I'll tell you when there's a new version of one of my apps, or a new project to try. Nothing else.