API keys and the API
Use a team API key to read stats, manage sites, and send events or payments from your own servers.
The traffic.cx API lets your own servers do what the dashboard does: read your numbers, set up sites, goals and chart notes, and send events and payments. Every request carries a team API key.
Create a key
Owners and admins create keys in Team → API keys. You see a key once, when you create it, so copy it into your server's secrets straight away. traffic.cx stores only a hash of it.
- A key belongs to its team and works for every site of that team.
- Creating keys requires a paid plan. Keys created earlier keep working after a plan ends.
- Revoke a key in the same place. It stops working at once.
Keep keys on your server. Never put one in browser code, a mobile app or a public repository. The API refuses browser requests from other websites, so a key in a web page wouldn't work anyway.
Permissions
Give each key only the permissions its job needs.
| Permission | Scope | What it opens |
|---|---|---|
| Read stats | stats:read | The Stats API: queries, sites, goals, funnels, notes and current visitors |
| Manage sites | sites:write | The Sites API: add, change and remove sites, goals and chart notes |
| Send events | events:write | The Events API: pageviews and custom events from a server |
| Send payments | payments:write | The Payments API: record and remove payments |
A request a key's permissions don't cover answers 403.
Authenticate
Send the key as a bearer token on every request to https://api.traffic.cx:
bash
curl https://api.traffic.cx/v1/sites \
-H "Authorization: Bearer YOUR_API_KEY"Request and response bodies are JSON. Send Content-Type: application/json with every body.
Limits
- Stats and Sites APIs: 600 requests per hour per key. Use
POST /v1/query/batchto send up to 12 queries in one request. - Events API: up to 25 events per request. Each visitor's address has the same per-minute limits as the tracker.
- Queries: up to 3 dimensions and 1,000 rows per page, and a 10-second time limit.
Past the hourly limit, the API answers 429 with retry_after, the number of seconds to wait.
Errors
Errors are JSON with a readable error. Most also name the field at fault in path, and some carry a stable code.
json
{ "error": "Unknown metric \"revenue!\"", "path": "metrics[0]" }| Status | Meaning |
|---|---|
400 | Something in the request is invalid; path names it |
401 | No key, or a key that is unknown or revoked |
402 | The team's dashboards are locked until it chooses a plan (code: "plan_required") |
403 | The key's permissions don't cover this request |
404 | No such site, or a site of another team |
409 | A limit was reached, such as the number of sites or goals |
429 | Too many requests (code: "rate_limited", retry_after) |
OpenAPI description
A machine-readable OpenAPI 3.1 description covers every endpoint here, including the Payments API. Import it into Postman, Insomnia or a code generator.