Stats API and MCP server
1. Create a key
Open your dashboard, go to Reports, then Stats API and MCP, and press Create API key. Copy the key straight away: Countnest stores only a fingerprint (SHA-256 hash) of it and can't show it again. Owners and editors can create and revoke keys. Each key reads one site.
2. Call the API
Send the key in the Authorization header. All endpoints are GET and return JSON.
curl -H "Authorization: Bearer cnk_your_key" "https://countnest.com/api/v1/stats?period=30d"
| Endpoint | What it returns |
|---|---|
/api/v1/site | The site name, domains, tracking ID and timezone |
/api/v1/stats | Visitors, visits, pageviews, events, bounce rate, average visit seconds, pages per visit, AI visitors, orders and revenue, plus the previous period and % change |
/api/v1/timeseries | Visitors, pageviews and AI visitors per hour or day (interval) |
/api/v1/breakdown | Top values for one dimension (by), up to limit rows (1 to 100, default 25) |
Periods: period is 24h, today, yesterday, 7d (default), 30d, 60d or 90d, in the site's timezone. For any other range use period=custom&from=2026-10-01&to=2026-10-31 (up to 366 days).
Breakdowns (by): pages, entry_pages, exit_pages, referrers, channels, ai_engines, countries, cities, devices, browsers, os, utm_sources, utm_mediums, utm_campaigns, events, goals, site_search, search_queries and search_pages (from Google Search Console and Bing, when connected).
Example response from /api/v1/breakdown?by=ai_engines&period=7d:
{ "by": "ai_engines", "period": { "label": "7d", "timezone": "Europe/Copenhagen" },
"results": [ { "value": "chatgpt", "visitors": 42 }, { "value": "perplexity", "visitors": 11 } ] }
3. Limits and errors
- 60 requests a minute per key. Over that you get HTTP 429 with
Retry-After: 60. - 401: missing, wrong or revoked key. 403: the plan does not include the API. 402: no active plan.
- 400: a bad parameter, with a message that says which one.
4. Connect an AI assistant (MCP)
Countnest has a small read-only Model Context Protocol server at:
https://countnest.com/api/mcp
It uses Streamable HTTP with JSON responses and the same key in the Authorization: Bearer header. Tools: get_site, get_stats, get_timeseries and get_breakdown, with the same periods and breakdowns as the API.
In a client that supports remote MCP servers with custom headers, add a server with that URL and the header Authorization: Bearer cnk_your_key. For a client that only runs local servers (for example Claude Desktop's config file), you can bridge with the open-source mcp-remote package:
{ "mcpServers": { "countnest": { "command": "npx",
"args": ["mcp-remote", "https://countnest.com/api/mcp", "--header", "Authorization: Bearer cnk_your_key"] } } }
Then ask, for example: "Which pages got more visits from ChatGPT this month than last month?"
Privacy: the AI tool you connect receives the aggregate numbers it asks for, under that tool's own terms. Countnest never sends your data to an AI provider by itself, and there is no visitor-level data to send.
Questions and answers
Which plans include the API?
Growth and Agency. Starter accounts see an upgrade note in Reports.
Can a key change anything?
No. Every endpoint and MCP tool is read-only. There is no endpoint that writes, deletes or exports raw visits.
Does the API return personal data?
No. It returns the same aggregates as the dashboard: counts, rates and top values. It never returns IP addresses, visitor codes, session IDs or single visits.
What happens if a key leaks?
Revoke it in Reports. It stops working on the next request. Keys also stop working when the person who created them leaves the team or the plan ends.
Does Countnest run an AI chatbot on my data?
No. The MCP endpoint only answers requests from the AI tool you connect, with your key. Countnest does not send your stats to any AI provider.
30-day free trial, no card required. Then from $14 a month. Cancel anytime.
Start free for 30 days