Docs › API

API

Read your stats as JSON: totals, a daily series and your dashboard’s top lists. With a key, also manage sites, settings and funnels.

Using an AI assistant? Connect it with the MCP server.

Authentication

Public sites need no key. For a private site, send an API key in the Authorization header.

Authorization: Bearer sim_key_YOUR_KEY

Make keys on your account page. Header only, from your server. Never put a key in a URL or a web page.

Endpoint

GET https://simplytics.dev/api/v1/stats/{domain}
ParameterDefaultAccepts
start, endThe last 30 daysDates as YYYY-MM-DD, in your site’s timezone. Up to 400 days.
includeNoneAny of the lists below, comma-separated.
limit10Rows per list, 1 to 1000.
metricvisitorsvisitors or views: what the lists count and rank by.
country, page, source…NoneFilters: count only visits that match every one given. Any of page, entry_page, exit_page, source, channel, campaign (as the campaigns list names it, or source|medium|campaign), country (a two-letter code), region (country|region code|region), city (country|region code|region|city), browser, os, device.

With metric=views, lists count views instead, as in {page, views}. The lists table notes the exceptions.

Filter by the dashboard’s rows, as in ?country=IN&page=/pricing. Every total and list then counts only the matching visits.

The answer adds filters and filters_first_date, the first day filters can count.

A key needs the filter’s list in its scope. Without a key, a list the owner hides can’t be a filter.

Lists

Any include also adds bounce_rate, a percent, and avg_duration_seconds to the totals.

includeEach row
daily{date, visitors, views, sessions} One per day, oldest first.
pages{page, visitors} Top pages.
entry_pages{page, visitors, entries} Pages visits began on. Both counts; metric picks the order, entries first for views.
exit_pages{page, visitors, exits} Pages visits ended on, the same way.
sources{source, visitors} Referring sites.
channels{channel, visitors} Direct, Search, Social, AI, Email and Referral. Always visitors.
countries{code, name, visitors} Two-letter country code and its English name.
regions{region, region_code, country: {code, name}, visitors} State or province, with its country. Its places_first_date is deprecated: use counted_from.
cities{city, region, region_code, country: {code, name}, visitors} With region and country, so cities that share a name stay apart.
devices{device, visitors} Desktop, Mobile and Tablet.
browsers{browser, visitors}
os{os, visitors}
campaigns{campaign, visitors} UTM source and campaign.
events{name, count, visitors} Custom events, most fired first, with either metric. Up to 50.
clicks{outbound: [...], downloads: [...]} Rows are {target, visitors}, or {target, clicks} with metric=views. Up to 10 of each.
hours{timezone, days, views, visitors, day_counts, first_date} Traffic by weekday and hour in your site’s timezone: 7 rows of 24, Monday first. A visitor counts once in each hour they visited. day_counts says how many of each weekday the range covers, for averages. Not cut by limit. Its first_date is deprecated: use counted_from.

Entry and exit pages, hours, regions and cities also add counted_from, as in {"visits": null, "places": "2026-11-12"}.

Examples

Totals for a public site

curl https://simplytics.dev/api/v1/stats/example.com
{
  "domain": "example.com",
  "period": {"start": "2026-10-02", "end": "2026-10-31"},
  "visitors": 1204,
  "views": 3310,
  "sessions": 1587
}

Top pages and countries

curl -H "Authorization: Bearer sim_key_YOUR_KEY" \
  "https://simplytics.dev/api/v1/stats/example.com?include=pages,countries&limit=3"
{
  "domain": "example.com",
  "period": {"start": "2026-10-02", "end": "2026-10-31"},
  "visitors": 1204,
  "views": 3310,
  "sessions": 1587,
  "bounce_rate": 46,
  "avg_duration_seconds": 71,
  "pages": [
    {"page": "/", "visitors": 702},
    {"page": "/pricing", "visitors": 311},
    {"page": "/blog/hello", "visitors": 148}
  ],
  "countries": [
    {"code": "US", "name": "United States", "visitors": 380},
    {"code": "IN", "name": "India", "visitors": 233},
    {"code": "DE", "name": "Germany", "visitors": 121}
  ]
}

Three days, day by day

curl -H "Authorization: Bearer sim_key_YOUR_KEY" \
  "https://simplytics.dev/api/v1/stats/example.com?start=2026-10-01&end=2026-10-03&include=daily"
{
  "domain": "example.com",
  "period": {"start": "2026-10-01", "end": "2026-10-03"},
  "visitors": 124,
  "views": 329,
  "sessions": 157,
  "bounce_rate": 44,
  "avg_duration_seconds": 68,
  "daily": [
    {"date": "2026-10-01", "visitors": 41, "views": 112, "sessions": 52},
    {"date": "2026-10-02", "visitors": 38, "views": 97, "sessions": 47},
    {"date": "2026-10-03", "visitors": 45, "views": 120, "sessions": 58}
  ]
}

Public sites

Without a key, a public site’s API shows what its public dashboard shows.

Search terms

GET https://simplytics.dev/api/v1/search_terms/{domain}

The Google searches that show your site, most clicks first. Connect Search Console on the dashboard first; see Google Search Console.

ParameterDefaultAccepts
start, endThe last 30 daysDates as YYYY-MM-DD. Up to 400 days.
limit10Search terms, most clicks first, 1 to 1000.

A key needs analytics:read and search terms in its data (Everything includes them).

{
  "domain": "fernhill.coffee",
  "period": {"start": "2026-10-14", "end": "2026-11-12"},
  "property": "sc-domain:fernhill.coffee",
  "totals": {"clicks": 1352, "impressions": 81824, "ctr": 0.0165, "position": 9.3},
  "data_through": "2026-11-10",
  "search_terms": [
    {"query": "fernhill coffee", "clicks": 398, "impressions": 1708, "ctr": 0.233, "position": 1.1},
    {"query": "single origin coffee beans", "clicks": 95, "impressions": 5936, "ctr": 0.016, "position": 6.8}
  ]
}

Keys

Make as many keys as you need, of two kinds:

An access key has a name and a scope:

ScopeChoices
SitesAll, including sites you add later, or a list of your domains.
DataEverything, or totals plus the lists you pick. cities also reads regions and countries, and entry_pages or exit_pages reads pages: each row names them. search_terms reads search terms.
Permissionsanalytics:read reads stats. The others are under Manage sites and funnels.

A key outside its scope gets a 403 naming what it can’t do, like {"error": "This key can't read example.com"}.

To rotate a key, make a new one, switch your code to it, then delete the old one. To rotate the master key, roll it.

An access key can expire, if you pick a time as you make it. Then it gets a 401. A master key never expires.

Make a key with the master key

POST https://simplytics.dev/api/v1/keys

Send JSON with a name and permissions. Sites and data default to all. ["keys:create"] alone makes a master key, if the account has none.

To make a key expire, add "expires_at": "2026-12-31T23:59:00Z". Leave it out for never.

curl -X POST -H "Authorization: Bearer sim_key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekly report", "permissions": ["analytics:read"], "sites": ["example.com"], "data": ["pages"]}' \
  https://simplytics.dev/api/v1/keys
{
  "id": 12,
  "name": "Weekly report",
  "last4": "Qx3w",
  "kind": "access",
  "permissions": [
    "analytics:read"
  ],
  "sites": [
    "example.com"
  ],
  "data": [
    "pages"
  ],
  "created_at": "2026-10-31T09:30:00.000Z",
  "created_by": "key:3",
  "last_used_at": null,
  "expires_at": null,
  "key": "sim_key_4dQj…Qx3w"
}

The new key is in this answer only, so store it then.

List, roll and delete keys

GET https://simplytics.dev/api/v1/keys
POST https://simplytics.dev/api/v1/keys/{id}/roll
DELETE https://simplytics.dev/api/v1/keys/{id}

The master key lists every key on the account, never a secret.

Roll gives a key a new secret, in its answer only. The old one stops at once.

Manage sites and funnels

An access key with the right permissions can add, change and delete your sites and funnels, and set each site’s logo and custom domain.

It can manage your invite link too.

Nothing in the API adds views or visitors or changes a count.

PermissionLets a key
analytics:readRead stats.
sites:readList sites.
sites:editAdd sites.
sites:deleteDelete sites.
funnels:readRead funnels and their counts.
funnels:editMake and rename funnels.
funnels:deleteDelete funnels.
settings:readRead a site’s settings and custom domain.
settings:editChange a site’s settings and logo and custom domain.
history:exportDownload the export ZIP.
referrals:readRead your invite link and its counts.
referrals:editChange its ending, or use an old one again.
referrals:deleteDelete an old ending.
revenue:readRead revenue. No key can connect or disconnect Stripe.
keys:createThe master key: make, list, roll and delete keys. Nothing else.

Delete is its own permission: edit never includes it. history:import isn’t available yet.

Paths are under https://simplytics.dev/api/v1.

EndpointNeedsDoes
GET /sitessites:readYour sites, in dashboard order.
POST /sitessites:editAdds a site, as the dashboard does, and returns its tracking tag. Body: {"domain": …, "timezone": …}.
GET /sites/{domain}settings:readIts visibility, badge, timezone, when it was added, its custom_domain, logo_url, logo_source (upload, favicon or null), public_hidden, public_compare, revenue (its Stripe connection, or null) and search_console: the Search Console property the dashboard shows and its status (ok or reconnect), or null. Connecting either is in the dashboard.
PATCH /sites/{domain}settings:editAny of visibility (private, public, badge_only), badge (any of metric, period, style, color, label, number, ticker_days; see Badge), timezone, public_hidden and public_compare.
DELETE /sites/{domain}sites:deleteDeletes it and its stats for good.
GET /sites/{domain}/custom_domainsettings:readIts custom domain: hostname, status, the CNAME record to add, and the snippet once it is active. Null if it has none.
POST /sites/{domain}/custom_domainsettings:editAdds one: {"hostname": "stats"} for stats.{domain}, or the full name.
DELETE /sites/{domain}/custom_domainsettings:editRemoves it.
PUT /sites/{domain}/logosettings:editSets its logo: the image itself as the body (PNG, JPEG or WebP, up to 100 KB), or {"source": "favicon"} to use your site’s own icon.
DELETE /sites/{domain}/logosettings:editRemoves it.
GET /sites/{domain}/funnelsfunnels:readEach funnel’s steps and counts for start to end (UTC days), 25 at a time. For the next 25, pass after: the response’s next_after (null on the last page). A funnel with "counting": true is still counting its past days; its counts are null until then. Without a key, a public site’s funnels: see Public sites.
POST /sites/{domain}/funnelsfunnels:editMakes a funnel: name (up to 100 characters) and at least 2 steps, any number of page paths up to 512 characters each and 16 KB in all. A full link of the site becomes its path. Its past days are counted within a minute or two. Unlimited funnels on every paid plan; up to 100 during the free trial.
PATCH /sites/{domain}/funnels/{id}funnels:editA new name, new steps, or both. New steps replace it with a new funnel, so they need funnels:delete too, and we email you first. The answer’s id is the new one and replaced the old.
DELETE /sites/{domain}/funnels/{id}funnels:deleteDeletes it and its counts for good.
GET /sites/{domain}/exporthistory:exportThe dashboard’s Everything (ZIP) export, for start to end.
GET /referralreferrals:readYour invite link: link, ending, old_endings (each still credits you), invited, paid, months_earned and campaigns (invited and paid per ?c= label).
PATCH /referralreferrals:edit{"ending": "maya-writes"}: a new ending (3–30 letters, numbers or hyphens, with no hyphen first, last or twice in a row; first come, first served), or one of your old ones to use again. The old link keeps crediting you.
DELETE /referral/endings/{ending}referrals:deleteDeletes an old ending. Links with it stop crediting you, and anyone may choose it next. Your current and original endings can’t be deleted.
GET /revenue/{domain}revenue:readRevenue from the site’s Stripe account for start to end: totals, the daily series, and new sales by source, campaign, country, device and landing page. See Revenue.

Add a site

curl -X POST -H "Authorization: Bearer sim_key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "shop.example.com", "timezone": "Europe/Berlin"}' \
  https://simplytics.dev/api/v1/sites
{
  "domain": "shop.example.com",
  "verified": false,
  "visibility": "private",
  "badge": {"metric": "visitors", "period": "month", "style": "flat", "color": "#2675ac", "color_shown": "#2675ac", "label": null, "number": "compact", "ticker_days": 30},
  "timezone": "Europe/Berlin",
  "created_at": "2026-11-02T09:30:00.000Z",
  "custom_domain": null,
  "logo_url": null,
  "logo_source": null,
  "revenue": null,
  "public_hidden": [

  ],
  "public_compare": true,
  "search_console": null,
  "snippet": "<script async src=\"https://simplytics.dev/track.js\" data-key=\"a1b2c3d4\"></script>"
}

Make a dashboard public

curl -X PATCH -H "Authorization: Bearer sim_key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "public"}' \
  https://simplytics.dev/api/v1/sites/example.com
{
  "domain": "example.com",
  "verified": true,
  "visibility": "public",
  "badge": {"metric": "visitors", "period": "month", "style": "flat", "color": "#2675ac", "color_shown": "#2675ac", "label": null, "number": "compact", "ticker_days": 30},
  "timezone": "Europe/Berlin",
  "created_at": "2026-06-14T08:12:44.000Z",
  "custom_domain": null,
  "logo_url": null,
  "logo_source": null,
  "revenue": null,
  "public_hidden": [

  ],
  "public_compare": true,
  "search_console": null
}

Hide stats from visitors

curl -X PATCH -H "Authorization: Bearer sim_key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public_hidden": ["visitors", "pages"]}' \
  https://simplytics.dev/api/v1/sites/example.com
{
  "domain": "example.com",
  "verified": true,
  "visibility": "public",
  "badge": {"metric": "visitors", "period": "month", "style": "flat", "color": "#2675ac", "color_shown": "#2675ac", "label": null, "number": "compact", "ticker_days": 30},
  "timezone": "Europe/Berlin",
  "created_at": "2026-06-14T08:12:44.000Z",
  "custom_domain": null,
  "logo_url": null,
  "logo_source": null,
  "revenue": null,
  "public_hidden": [
    "visitors",
    "pages"
  ],
  "public_compare": true,
  "search_console": null
}

Change the badge

curl -X PATCH -H "Authorization: Bearer sim_key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badge": {"style": "ticker", "ticker_days": 90, "color": "#f2c94c", "label": "Example Shop"}}' \
  https://simplytics.dev/api/v1/sites/example.com
{
  "domain": "example.com",
  "verified": true,
  "visibility": "public",
  "badge": {"metric": "visitors", "period": "month", "style": "ticker", "color": "#f2c94c", "color_shown": "#93720b", "label": "Example Shop", "number": "compact", "ticker_days": 90},
  "timezone": "Europe/Berlin",
  "created_at": "2026-06-14T08:12:44.000Z",
  "custom_domain": null,
  "logo_url": null,
  "logo_source": null,
  "revenue": null,
  "public_hidden": [
    "visitors",
    "pages"
  ],
  "public_compare": true,
  "search_console": null
}

Start visitors without the comparison

curl -X PATCH -H "Authorization: Bearer sim_key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public_compare": false}' \
  https://simplytics.dev/api/v1/sites/example.com
{
  "domain": "example.com",
  "verified": true,
  "visibility": "public",
  "badge": {"metric": "visitors", "period": "month", "style": "ticker", "color": "#f2c94c", "color_shown": "#93720b", "label": "Example Shop", "number": "compact", "ticker_days": 90},
  "timezone": "Europe/Berlin",
  "created_at": "2026-06-14T08:12:44.000Z",
  "custom_domain": null,
  "logo_url": null,
  "logo_source": null,
  "revenue": null,
  "public_hidden": [
    "visitors",
    "pages"
  ],
  "public_compare": false,
  "search_console": null
}

Make a funnel

curl -X POST -H "Authorization: Bearer sim_key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Signup", "steps": ["/", "/pricing", "/signup"]}' \
  https://simplytics.dev/api/v1/sites/example.com/funnels
{
  "id": 41,
  "name": "Signup",
  "steps": [
    "/",
    "/pricing",
    "/signup"
  ]
}

Delete a site

curl -X DELETE -H "Authorization: Bearer sim_key_YOUR_KEY" \
  https://simplytics.dev/api/v1/sites/example.com
{
  "domain": "example.com",
  "deleted": true
}

Export everything

curl -H "Authorization: Bearer sim_key_YOUR_KEY" -o example.com.zip \
  "https://simplytics.dev/api/v1/sites/example.com/export?start=2026-10-01&end=2026-10-31"

The same ZIP as the dashboard’s export. It holds every list, so the key’s data must be Everything.

Logo and custom domain

Each needs the same check as Public: our tag on your homepage, or a DNS record. It runs on its own.

Removing an active custom domain emails you first, naming the key. A snippet loading from it stops counting.

If the email can’t go, nothing is removed. Logo changes and other custom domain changes don’t email you.

Send the logo as the request body. We read its type from the file itself, so an SVG is refused even when named .png.

Or send {"source": "favicon"}: we use your site’s sharpest icon, an SVG when it has one, and keep it up to date.

A custom domain is pending until its CNAME to proxy.simplytics.dev is live, then active, with its own snippet.

Once active, snippet_in_use says whether your pages load its snippet: all, some (an old snippet is still in use) or none.

The rules are on Custom domains.

Add a custom domain

curl -X POST -H "Authorization: Bearer sim_key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "stats"}' \
  https://simplytics.dev/api/v1/sites/example.com/custom_domain
{
  "domain": "example.com",
  "custom_domain": {"hostname": "stats.example.com", "status": "pending", "detail": null, "record": {"type": "CNAME", "name": "stats.example.com", "target": "proxy.simplytics.dev"}, "snippet": null, "snippet_in_use": null}
}

Upload a logo

curl -X PUT -H "Authorization: Bearer sim_key_YOUR_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @logo.png \
  https://simplytics.dev/api/v1/sites/example.com/logo
{
  "domain": "example.com",
  "logo_url": "https://simplytics.dev/logo/3f9c2e7a51b84d06c1e9a8f27d4b6035e81c9f4a72d6b0e3958a1c4f7e2d6b90.png",
  "logo_source": "upload"
}

Use your site’s icon

curl -X PUT -H "Authorization: Bearer sim_key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "favicon"}' \
  https://simplytics.dev/api/v1/sites/example.com/logo
{
  "domain": "example.com",
  "logo_url": "https://simplytics.dev/logo/favicon/8d41c07be2a95f36d0e1b74c29a8f5e3.png",
  "logo_source": "favicon"
}

Revenue

Connect Stripe in the site’s Revenue settings on the dashboard. The API reads what it counted.

Amounts are in the currency’s smallest unit (cents), as Stripe gives them.

A public site needs no key. Its answer is what its dashboard shows, with test_mode for connection.

curl -H "Authorization: Bearer sim_key_YOUR_KEY" \
  "https://simplytics.dev/api/v1/revenue/example.com?start=2026-11-01&end=2026-11-30"
{
  "domain": "example.com",
  "period": {"start": "2026-11-01", "end": "2026-11-30"},
  "connection": {"provider": "stripe", "mode": "live", "sync": "webhook", "status": "ok", "connected_at": "2026-11-01T09:12:30.000Z", "last_payment_at": "2026-11-30T17:41:05.000Z"},
  "currency": "usd",
  "currencies": [
    "usd",
    "eur"
  ],
  "totals": {"gross": 184600, "refunds": 4900, "net": 179700, "payments": 62, "refund_count": 1, "new": {"gross": 124600, "payments": 34}, "renewals": {"gross": 60000, "payments": 28}},
  "daily": [
    {"date": "2026-11-01", "gross": 7300, "refunds": 0, "net": 7300}
  ],
  "sources": [
    {"value": "google.com", "revenue": 34300, "payments": 9, "refunds": 0},
    {"value": "news.ycombinator.com", "revenue": 24500, "payments": 5, "refunds": 4900}
  ],
  "campaigns": [
    {"value": "newsletter / autumn-launch", "revenue": 14700, "payments": 3, "refunds": 0}
  ],
  "countries": [
    {"value": "US", "revenue": 49000, "payments": 14, "refunds": 0}
  ],
  "devices": [
    {"value": "desktop", "revenue": 73500, "payments": 20, "refunds": 4900}
  ],
  "pages": [
    {"value": "/pricing", "revenue": 44100, "payments": 11, "refunds": 0}
  ]
}
FieldHolds
totalsgross, refunds, net, payments and refund_count; new and renewals. Only this site’s sales: those a visit to it names, and renewals of subscriptions they started.
dailyEach day with a payment or refund.
sources, campaigns, countries, devices, pagesNew revenue credited to each, largest first, limit rows (default 10, at most 100). Renewals are never credited.
currencyThe one the numbers are in: currency= picks it, else the one with the most revenue. currencies lists every one in the range.

Badge

FieldValues
metricvisitors or views.
periodmonth or all, for flat and pill.
styleflat, pill or ticker (the count for its window, a line of it and the change on as many days before).
ticker_daysThe ticker’s window: 7, 30 (the default), 90 or 365 complete days, ending yesterday. The change reads – until the site is two windows old.
colorA hex colour, like #2675ac, or null for that default. If white text on it would be hard to read, the badge draws a darker shade: color_shown.
labelnull for the domain, "" for none, or up to 24 letters, digits, spaces and . - _ '.
numbercompact (1.2k) or full (1,234).

Send only the fields you change. Embedded badges update within 5 minutes.

Public and badge-only

Turning either on checks that you control the domain, as the dashboard does, then emails you. If the email can’t go, nothing changes.

What visitors see

public_hidden lists what your public dashboard hides from visitors. Send the whole list; [] shows everything. Names we don’t know are dropped.

NameHides
visitorsVisitors
viewsViews
sessionsSessions
bounce_rateBounce Rate
views_per_sessionViews/Session
avg_durationAvg. Duration
liveCurrent visitors
revenueRevenue
pagesPages
entry_pagesEntry pages
exit_pagesExit pages
sourcesTop Sources
channelsChannels
countriesCountries
regionsRegions
citiesCities
devicesDevices
browsersBrowsers
osOS
campaignsCampaigns
eventsEvents
clicksClicks
hoursViews by hour
search_termsSearch terms
heatmapViews by day
funnelsFunnels

Hiding a total also turns that metric’s numbers in the cards into percentages. Hiding Views or Sessions hides Views/Session too.

Hiding Pages hides Entry pages, Exit pages and Funnels too.

public_compare says whether your public dashboard starts with vs previous period on (true, the default) or off. Visitors can still switch it.

Your own dashboard and your keys still get everything.

While the dashboard is public, the badge never shows a stat you hid; badge-only mode shows what you set.

Deletes

A delete is permanent, as on the dashboard. We email you first, naming the key. If the email can’t go, nothing is deleted.

Good to know

Errors

Errors come as JSON with a message, like {"error": "Subscription required"}.

StatusWhen
400A parameter or field is wrong. The message names it.
401The key is wrong, was deleted or expired.
403No key and the site is not public, the subscription has ended, the key’s scope doesn’t cover the request, or we couldn’t confirm you control the domain. The message says which.
404No verified site with that name on the key’s account, or no custom domain or logo to remove.
409The site is already added, has had no visits yet, changed while saving or deleting, already has a custom domain, the hostname is already in use, waits for Check now beside Public on its dashboard, or a free trial already has 100 funnels. For search terms: Search Console isn’t connected, or Google refused or didn’t answer.
413, 415The logo is over 100 KB, or isn’t a PNG, JPEG or WebP.
422We couldn’t find an icon on your site.
502, 503We couldn’t email you about a delete, new funnel steps, a public change or removing an active custom domain, so nothing changed. Or Cloudflare refused a custom domain.
429Too many requests from your address, with your key or across your account’s keys, 100 new keys or 10 emailed changes in a day, or a second check that you control the domain within a minute. Wait the seconds in Retry-After.

Limits