TraceAPI and MCP
Read your analytics programmatically with the REST API, or connect an AI assistant over MCP.
Trace has a read-only REST API for your stats and an MCP endpoint for AI assistants. Both use the same API keys. Settings → API / MCP shows the site's ID and links to where keys are created.
API keys
There are two kinds of key:
| Key | Where to create it | Acts as |
|---|---|---|
| Personal API key | Your Account page | You, with your own role and site access. |
| Workspace API key | The Workspace settings page (admins and owners) | An admin on every site in the workspace. |
To create one, click Create API Key, give it a name (up to 32 characters) and click Create. Tick Restrict permissions to limit the key to chosen resources (Analytics, Sessions, Events, Users, Goals, Funnels, Session replay, Sites, Workspace), each with read or write access.
The key is shown once — copy it before closing the dialog. Revoke keys you no longer need.
Authentication
Send the key as a bearer token on every request:
curl "https://data.whos1.bid/api/v1/sites" \
-H "Authorization: Bearer YOUR_API_KEY"Every endpoint except /sites needs a site_id query parameter — your site's ID, shown in Settings → API / MCP (it's the same as data-website-id).
| Status | Meaning |
|---|---|
| 400 | site_id is missing — list your sites with GET /api/v1/sites. |
| 401 | The API key is invalid or missing. |
| 403 | The key's permissions or your role don't allow this. |
| 404 | The site wasn't found. |
Endpoints
Base URL: https://data.whos1.bid/api/v1. Responses are JSON with the results in data; most also include the site name and the resolved date range.
| Endpoint | Parameters | Returns |
|---|---|---|
GET /sites | — | Your sites: id, name, domain, timezone. |
GET /analytics/overview | range, optional fields | One row with visitors, sessions, pageviews, bounceRate (0–1) and avgSessionDurationSeconds. |
GET /analytics/realtime | — | visitors active in the last 45 seconds. |
GET /analytics/breakdown | dimension (required), range | Top values for a dimension (see below). |
GET /analytics/goals | range | Every goal with visitors (unique conversions), events (total, null for scroll goals) and conversionRate. |
GET /analytics/properties | — | The custom properties shown on the dashboard. |
GET /analytics/funnels | — | Your funnels: id, name, stepsCount. |
GET /analytics/funnels/{id} | range, optional compare=1 | The funnel report, optionally compared with the previous period. |
curl "https://data.whos1.bid/api/v1/analytics/overview?site_id=YOUR_WEBSITE_ID&range=last7d" \
-H "Authorization: Bearer YOUR_API_KEY"Ranges
range accepts now (last 30 minutes), today, yesterday, last24h, last7d, last30d (the default), last12months, weektodate, monthtodate, yeartodate and alltime. Dates follow the site's timezone.
Breakdown dimensions
dimension | Returns |
|---|---|
channel, referrer, campaign, keyword, country, region, city, browser, os, device | The top 10 values with their visitors. |
event:page, visit:entry_page, visit:exit_page | Up to 100 pages with their metrics. |
visit:country, visit:region, visit:city | Up to 100 locations with codes, names and metrics. |
event:props:<key> | Up to 100 values of a custom property, with visitors, events and share. |
MCP
Connect an MCP-capable AI assistant to https://data.whos1.bid/api/mcp, sending your API key as a bearer token. It offers these tools:
| Tool | What it does |
|---|---|
list_sites | Lists the sites the key can read. |
get_overview | Headline stats for a site and range. |
get_breakdown | Top values for one of the basic dimensions (channel, referrer, campaign, keyword, country, region, city, browser, os, device). |
list_goals | Goals with their conversions and conversion rate. |