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}

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

Lists

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

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.

• With include, the range snaps to the dashboard’s presets: the last 1, 7, 10, 30, 90, 180 or 365 days.
• Campaigns stop at 10.
• Answers carry Access-Control-Allow-Origin: *, so a web page can fetch them. Answers to a key do not.

Keys

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

• Access key: reads or changes your data, within its scope.
• Master key: makes, lists, rolls and deletes keys, and can’t see your data. Keys it makes can have any access. One per account.

An access key has a name and a scope:

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.

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

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

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

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"},
  "timezone": "Europe/Berlin",
  "created_at": "2026-11-02T09:30:00.000Z",
  "custom_domain": null,
  "logo_url": 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"},
  "timezone": "Europe/Berlin",
  "created_at": "2026-06-14T08:12:44.000Z",
  "custom_domain": null,
  "logo_url": 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.

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

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}
}

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"
}

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.

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

• The timezone is your account’s, for every site, so only a key for all sites can change it.
• To change a funnel’s steps, make a new funnel and delete the old one.
• A key limited to some sites can only add those domains.

Errors

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

Limits

• 60 requests a minute per IP address.
• 60 requests a minute per key, from any number of addresses.
• 600 requests a minute across all of an account’s keys.
• Without a key, 30 a minute with include.
• A range longer than 400 days keeps its latest 400.
• 100 new keys a day per account. No limit on how many you keep.
• 10 emailed changes (deletes, public, removing an active custom domain) a day per account. Past that, they wait until tomorrow.