REST API

The Statsdot API gives you the same data as your dashboard, as JSON, and lets you manage sites, goals, your team and tokens. Every request needs a personal access token.

Authentication

Create a token on the API and MCP page of your account. Choose read only for scripts and reports, or read and write if the token should also change things. Copy the token when it is shown: it is not shown again.

Send it in the Authorization header of every request:

curl https://statsdot.com/api/v1/sites \
  -H "Authorization: Bearer 12|your-token" \
  -H "Accept: application/json"

A token sees what its user sees: your own sites and the sites of the teams you belong to, with your role there. A viewer can read a team site, a manager can also change it, and only the owner can delete it.

Base URL and format

• Base URL: https://statsdot.com/api/v1
• Requests and responses are JSON. Successful responses wrap the result in data.
• Times are ISO 8601 in UTC.

Ranges and filters

Every statistics endpoint accepts the same query parameters as the dashboard:

Parameter	Values
range	today, 7d, 30d (default), 12m, or a custom range 2026-09-01~2026-09-30 (whole UTC days, at most two years)
filters[page]	Only hits on this page path
filters[entry]	Visits that started on this page
filters[source]	Referrer domain, for example google.com; empty means direct
filters[utm_source], filters[utm_medium], filters[utm_campaign]	Campaign tags of the landing page
filters[country]	ISO country code, for example ES
filters[device]	Desktop, Mobile or Tablet
filters[browser], filters[os]	As shown in the dashboard
filters[event]	Visits that sent this event
filters[goal]	Visits that reached this goal id

Visitors over a range are visitor-days: Statsdot counts a visitor once per day, because the visitor code changes every day.

Statistics

Method and path	What it returns
GET /sites/{site}/stats/overview	Visitors, pageviews, bounce rate and visit duration (seconds), with the previous period of the same length and the change in percent
GET /sites/{site}/stats/timeseries	Visitors and pageviews per day, or per month for ranges over 90 days
GET /sites/{site}/stats/breakdown/{breakdown}	Top values of one dimension by visitors. breakdown is one of pages, entry_pages, exit_pages, referrers, utm_source, utm_medium, utm_campaign, countries, devices, browsers, operating_systems, events, event_labels (with event=Name). limit from 1 to 100, default 10
GET /sites/{site}/stats/goals	Each goal with visitors who reached it, conversions and conversion rate
GET /sites/{site}/stats/realtime	Visitors in the last five minutes
GET /sites/{site}/stats/bots	AI crawler requests in the period: total, per crawler, and the pages they read most (crawler=openai-gptbot narrows the pages). Needs AI crawler tracking; filters do not apply

Example:

curl "https://statsdot.com/api/v1/sites/42/stats/breakdown/referrers?range=7d&limit=5" \
  -H "Authorization: Bearer 12|your-token"

{
  "data": {
    "from": "2026-10-11T00:00:00+00:00",
    "to": "2026-10-17T10:15:00+00:00",
    "filters": {},
    "breakdown": "referrers",
    "rows": [
      { "value": "google.com", "visitors": 312 },
      { "value": "", "visitors": 145 }
    ]
  }
}

Account and sites

Method and path	What it does
GET /account	Your plan, events used this month and included, limits, and the token's abilities
GET /sites	Sites you can see, with your role, settings and tracking snippet
GET /sites/{site}	One site
POST /sites	Add a site: {"domain": "example.com"}. Add account_id to add it to a team account you manage. The plan limits of that account apply
PATCH /sites/{site}	Change weekly_report, public_live, shared (public read-only link), alert_traffic, alert_silence or main_goal_id (a goal of the site, or null)
DELETE /sites/{site}	Delete a site you own and all its statistics

Goals

Method and path	What it does
GET /sites/{site}/goals	The goals of a site
POST /sites/{site}/goals	{"type": "page", "value": "/thanks"} or {"type": "event", "value": "Signup"}
DELETE /sites/{site}/goals/{goal}	Delete a goal; the visits stay

Funnels

Method and path	What it does
GET /sites/{site}/funnels	The funnels of a site
POST /sites/{site}/funnels	{"name": "Sign-up", "steps": [{"type": "page", "value": "/"}, {"type": "page", "value": "/pricing"}, {"type": "event", "value": "Signup"}]}: 2 to 8 steps, at most 10 funnels per site
DELETE /sites/{site}/funnels/{funnel}	Delete a funnel
GET /sites/{site}/stats/funnels/{funnel}	Visitors at each step in order within the same day, with the share of the previous and of the first step; ranges and filters apply

Notes

Method and path	What it does
GET /sites/{site}/notes	Notes on the chart; from and to (YYYY-MM-DD) narrow the list
POST /sites/{site}/notes	{"date": "2026-10-17", "text": "Newsletter sent"}: a past or present day, up to 200 characters
DELETE /sites/{site}/notes/{note}	Delete a note

Team

Method and path	What it does
GET /team	People invited to your account, the plan's limit, and the teams you belong to
POST /team	Invite: {"email": "[email protected]", "role": "viewer"} (viewer or manager). The invitation email is sent; the response includes the invitation link
PATCH /team/{member}	Change the role
DELETE /team/{member}	Remove a person or a pending invitation

Tokens

Method and path	What it does
GET /tokens	Your tokens, with their abilities and last use
POST /tokens	{"name": "Reports", "abilities": ["read"]}. The plain token is in the response, once. A read-only token cannot create a write token
DELETE /tokens/{token}	Revoke a token

Errors

Errors use the HTTP status and a body with a stable code:

{ "error": { "code": "account_blocked", "message": "The account that owns this site has no active plan." } }

Status	When
401	Missing or invalid token
402	The account has no active plan, is over its plan, or has reached a limit
403	The token is read-only and the request changes something
404	The site, goal or member does not exist or is not available to this token
422	Invalid parameters, for example an unknown range or breakdown
429	Too many requests

Limits

• 120 requests per minute per token.
• At most 25 tokens per account.
• The API is included in every plan and in the trial.