API HTTP de lecture
Takt expose une API HTTP de lecture pour interroger les statistiques d’un site
depuis un programme ou un agent. Elle réutilise les endpoints /api/v1/sites/{domain}/stats/* et s’authentifie par clé d’API (pas de cookie de session).
Authentification
Crée une clé d’API avec la permission stats:read depuis les paramètres de ton org,
puis transmets-la en en-tête Authorization :
curl -H "Authorization: Bearer takt_sk_xxx" \
"https://taktlytics.com/api/v1/sites/exemple.com/stats/summary?from=2026-03-01T00:00:00Z&to=2026-03-08T00:00:00Z"Une clé est liée à un seul site. Une clé invalide renvoie 401 ; une clé sans la
bonne permission ou visant un autre domaine renvoie 404 (anti-énumération).
Endpoints
La plupart des routes de lecture sont sous /api/v1/sites/{domain}/stats/ : summary, timeseries, breakdown, realtime, goals, funnels, properties, revenue.
L’export CSV/JSON utilise un chemin distinct, /api/v1/orgs/{org}/sites/{domain}/stats/export,
avec la même authentification par clé. Le contrat détaillé (paramètres, schémas de
réponse) est décrit dans la spécification OpenAPI (api/openapi.yaml).
L’export est borné à 999 lignes et à 256 Ko de corps, comme l’outil MCP export_stats.
Au-delà, les pages les moins visitées sont coupées et l’export le signale par l’en-tête
de réponse X-Takt-Truncated, toujours présent, qui vaut true ou false. Le corps ne
change pas : un tableau de lignes en JSON, label,visitors,pageviews en CSV.
Avec des données importées, les pages live et importées sont fusionnées avant la borne.
Deux familles ont leur propre permission, en plus de stats:read qui les ouvre aussi :
| Route | Permission dédiée | Ce qu’elle renvoie |
|---|---|---|
stats/ai | ai:read | trafic venu des assistants et passages des crawlers IA |
stats/search-console | search_console:read | clics, impressions, CTR et position Google |
stats/search-console/drill | search_console:read | les mêmes chiffres figés sur une page ou une requête (dimension=page\|query, value=) |
Ces deux familles lisent des données rapatriées chez Google : elles exigent une
propriété Search Console rattachée au site, et répondent 409 tant que ce n’est pas
le cas.
Volume & limite de débit
L’API de lecture est incluse dans tous les plans, sans limite de volume. Chaque requête de lecture réussie est comptée dans l’usage de ton organisation, à titre informatif. Les refus (clé invalide, débit dépassé, mauvais domaine, accès restreint) ne sont pas comptés.
Une limite de débit anti-abus s’applique par clé d’API : 200 requêtes par 10
secondes et 600 requêtes par minute. Au-delà, l’endpoint répond 429 Too Many Requests (code trop_de_requetes) avec l’en-tête Retry-After, en
secondes (10 pour la rafale, 60 pour la minute). Chaque clé a son propre budget.
En amont, la passerelle applique aussi un plafond par adresse IP, toutes clés confondues : 20 requêtes par seconde, avec des pointes jusqu’à 100. Au-delà, elle répond 429 avec un corps HTML et sans en-tête Retry-After : attends une seconde avant de réessayer.
Si ton organisation n’a plus accès au produit (essai terminé, abonnement résilié),
les endpoints de lecture répondent 402 Payment Required (code acces_restreint).