The Stats API

What you can read

The Stats API answers with the same numbers as your dashboard, for the same site and range: the overview, any list, any chart, the “when people came” grid, and who’s on the site right now. It only reads. Nothing sent to it changes your sites or your stats.

Every route is a GET under:

https://app.crustat.com/api/v1/

The API reference lists each route, what it takes and what it answers.

Sign in with an API key

Your scripts and servers sign in with an API key. To make one, open Settings → API keys in Crustat and choose Create key. Give it a name you’ll recognise later, like the script that will use it, and pick the sites it may read: every site you can see, or only some of them.

Crustat shows the key once, right after you make it. Copy it then and keep it somewhere safe, such as your server’s environment variables. If you lose it, revoke it and make a new one.

Send the key in the Authorization header of every request:

curl -H "Authorization: Bearer $CRUSTAT_API_KEY" \
  "https://app.crustat.com/api/v1/sites"

What a key can do:

• It only reads. A key can’t change anything in your workspace.
• It sees what you see. A key reads as the person who made it. If your access changes later, for example you’re limited to fewer sites, the key follows. If you leave the workspace, your keys stop working.
• It belongs on a server. Anyone who has the key can read those stats, so keep it out of web pages and apps people download.

Owners and admins see every key in the workspace and can revoke any of them. Everyone else sees and revokes their own. To stop a key, choose Revoke next to it: it stops working at once.

Try it in your browser

Sign in to Crustat, then open this address in the same browser:

https://app.crustat.com/api/v1/sites

You’ll see your sites as JSON. Every route works this way while you’re signed in, so you can look at the answers before writing any code. It reads the workspace you have open in the dashboard.

Which sites

/api/v1/sites lists the sites you can read. Each one has an id: the same ID as in its tracking code (data-site). Pass it as site to the stats routes:

https://app.crustat.com/api/v1/stats/overview?site=AbC123_-xyzXYZ01&range=7d

You see what you see in the dashboard. A viewer limited to some sites gets only those (see Invite your team), and a site you can’t read answers 404, the same as one that doesn’t exist.

range is today, 7d or 30d, in the site’s time zone, as on the dashboard. Leave it out for 7d. If the site has other hostnames, add host to see one of them only.

Errors

Anything other than a 200 answers in the same shape:

{ "error": { "code": "not_found", "message": "Not found." } }

Check code. The message is for people reading your logs.

Status	code	What it means
400	bad_request	A parameter is missing or isn’t one of its values.
401	unauthorized	No valid API key and not signed in, the key was revoked, or you’re no longer in the workspace.
402	plan_required	The workspace has no plan: its trial ended or it was deactivated.
404	not_found	No such route, or no such site among yours.
429	rate_limited	Too many requests: wait the seconds in Retry-After.
500, 502	server_error	Something went wrong on our side. Try again in a moment.

Limits

Up to 120 requests a minute for each API key, or for you while you’re signed in to Crustat in the browser. Past that, the API answers 429 with a Retry-After header. Wait that many seconds and carry on.

The API sends no CORS headers, so web pages on other sites can’t read it from a visitor’s browser.

What stays the same

Version 1 keeps its routes and fields. New fields and new values may appear, so skip any you don’t know.