HTTP Read API
Takt exposes an HTTP Read API to query a site’s statistics from a program or an
agent. It reuses the /api/v1/sites/{domain}/stats/* endpoints and authenticates with
an API key (no session cookie).
Authentication
Create an API key with the stats:read permission from your org settings, then pass it
in the Authorization header:
curl -H "Authorization: Bearer takt_sk_xxx" \
"https://taktlytics.com/api/v1/sites/example.com/stats/summary?from=2026-03-01T00:00:00Z&to=2026-03-08T00:00:00Z" A key is bound to a single site. An invalid key returns 401; a key missing the
right permission or targeting another domain returns 404 (anti-enumeration).
Endpoints
Most read routes live under /api/v1/sites/{domain}/stats/: summary, timeseries, breakdown, realtime, goals, funnels, properties, revenue. CSV/JSON export
uses a distinct path, /api/v1/orgs/{org}/sites/{domain}/stats/export, with the same
key authentication. The detailed contract (parameters, response schemas) is described
in the OpenAPI specification (api/openapi.yaml).
The export is capped at 999 rows and a 256 KB body, like the export_stats MCP tool.
Beyond that, the least visited pages are cut and the export says so through the X-Takt-Truncated response header, always present, set to true or false. The body
does not change: an array of rows in JSON, label,visitors,pageviews in CSV.
With imported data, live and imported pages are merged before the cap.
Two families carry their own permission, on top of stats:read which also opens them:
| Route | Dedicated permission | What it returns |
|---|---|---|
stats/ai | ai:read | traffic coming from assistants and AI crawler hits |
stats/search-console | search_console:read | Google clicks, impressions, CTR and position |
stats/search-console/drill | search_console:read | the same numbers pinned to one page or query (dimension=page\|query, value=) |
Both families read data pulled from Google: they need a Search Console property linked
to the site, and answer 409 until that is done.
Volume & rate limit
The read API is included in every plan with no volume limit. Each successful read request is counted in your organization’s usage, for information only. Rejections (invalid key, rate limit exceeded, wrong domain, restricted access) are not counted.
An anti-abuse rate limit applies per API key: 200 requests per 10 seconds and 600 requests per minute. Past that, the endpoint returns 429 Too Many Requests (code trop_de_requetes) with a Retry-After header, in seconds (10 for the burst,
60 for the minute). Each key has its own budget.
Upstream, the gateway also applies a cap per IP address, across all keys: 20 requests per second, with bursts of up to 100. Past that, it answers 429 with an HTML body and no Retry-After header: wait one second before retrying.
If your organization no longer has access to the product (trial ended, subscription
canceled), read endpoints return 402 Payment Required (code acces_restreint).