API REST

L'API Statsdot vous fournit les mêmes données que votre tableau de bord, au format JSON, et vous permet de gérer vos sites, objectifs, votre équipe et vos jetons. Chaque requête nécessite un jeton d'accès personnel.

Authentification

Créez un jeton sur la page API et MCP de votre compte. Choisissez lecture seule pour les scripts et rapports, ou lecture et écriture si le jeton doit également effectuer des modifications. Copiez le jeton lorsqu'il s'affiche : il ne sera plus jamais visible.

Envoyez-le dans l'en-tête Authorization de chaque requête :

curl https://statsdot.com/api/v1/sites \
  -H "Authorization: Bearer 12|your-token" \
  -H "Accept: application/json"

Un jeton accède à ce que son utilisateur voit : vos propres sites et les sites des équipes auxquelles vous appartenez, avec votre rôle associé. Un lecteur peut consulter un site d'équipe, un gestionnaire peut également le modifier, et seul le propriétaire peut le supprimer.

URL de base et format

• URL de base : https://statsdot.com/api/v1
• Les requêtes et réponses sont au format JSON. Les réponses réussies enveloppent le résultat dans data.
• Les heures sont au format ISO 8601 en UTC.

Plages et filtres

Chaque point de terminaison de statistiques accepte les mêmes paramètres de requête que le tableau de bord :

Paramètre	Valeurs
range	today, 7d, 30d (par défaut), 12m, ou une plage personnalisée 2026-09-01~2026-09-30 (jours UTC complets, deux ans maximum)
filters[page]	Uniquement les accès sur ce chemin de page
filters[entry]	Visites ayant commencé sur cette page
filters[source]	Domaine référent, par exemple google.com ; vide signifie direct
filters[utm_source], filters[utm_medium], filters[utm_campaign]	Tags de campagne de la page d'atterrissage
filters[country]	Code pays ISO, par exemple ES
filters[device]	Desktop, Mobile ou Tablet
filters[browser], filters[os]	Tel qu'affiché dans le tableau de bord
filters[event]	Visites ayant envoyé cet événement
filters[goal]	Visites ayant atteint cet identifiant d'objectif

Les visiteurs sur une plage donnée sont des visiteurs-jours : Statsdot compte un visiteur une fois par jour, car le code visiteur change quotidiennement.

Statistiques

Méthode et chemin	Ce qu'il renvoie
GET /sites/{site}/stats/overview	Visiteurs, pages vues, taux de rebond et durée de visite (secondes), avec la période précédente de même durée et le changement en pourcentage
GET /sites/{site}/stats/timeseries	Visiteurs et pages vues par jour, ou par mois pour les plages supérieures à 90 jours
GET /sites/{site}/stats/breakdown/{breakdown}	Valeurs principales d'une dimension par visiteurs. breakdown est l'un des suivants : pages, entry_pages, exit_pages, referrers, utm_source, utm_medium, utm_campaign, countries, devices, browsers, operating_systems, events, event_labels (avec event=Nom). limit de 1 à 10, par défaut 10
GET /sites/{site}/stats/goals	Chaque objectif avec les visiteurs l'ayant atteint, les conversions et le taux de conversion
GET /sites/{site}/stats/realtime	Visiteurs au cours des cinq dernières minutes
GET /sites/{site}/stats/bots	Requêtes des robots d'indexation IA sur la période : total, par robot, et les pages les plus lues (crawler=openai-gptbot restreint les pages). Nécessite le suivi des robots IA ; les filtres ne s'appliquent pas

Exemple :

curl "https://statsdot.com/api/v1/sites/42/stats/breakdown/referrers?range=7d&limit=5" \
  -H "Authorization: Bearer 12|your-token"

{
  "data": {
    "from": "2026-10-11T00:00:00+00:00",
    "to": "2026-10-17T10:15:00+00:00",
    "filters": {},
    "breakdown": "referrers",
    "rows": [
      { "value": "google.com", "visitors": 312 },
      { "value": "", "visitors": 145 }
    ]
  }
}

Compte et sites

Méthode et chemin	Ce qu'il fait
GET /account	Votre formule, les événements utilisés ce mois-ci et inclus, les limites, et les capacités du jeton
GET /sites	Sites que vous pouvez voir, avec votre rôle, les paramètres et le snippet de suivi
GET /sites/{site}	Un site
POST /sites	Ajouter un site : {"domain": "example.com"}. Ajoutez account_id pour l'ajouter à un compte d'équipe que vous gérez. Les limites de la formule de ce compte s'appliquent
PATCH /sites/{site}	Modifier weekly_report, public_live, shared (lien public en lecture seule), alert_traffic, alert_silence ou main_goal_id (un objectif du site, ou null)
DELETE /sites/{site}	Supprimer un site dont vous êtes propriétaire et toutes ses statistiques

Objectifs

Méthode et chemin	Ce qu'il fait
GET /sites/{site}/goals	Les objectifs d'un site
POST /sites/{site}/goals	{"type": "page", "value": "/thanks"} ou {"type": "event", "value": "Signup"}
DELETE /sites/{site}/goals/{goal}	Supprimer un objectif ; les visites sont conservées

Entonnoirs

Méthode et chemin	Ce qu'il fait
GET /sites/{site}/funnels	Les entonnoirs d'un site
POST /sites/{site}/funnels	{"name": "Sign-up", "steps": [{"type": "page", "value": "/"}, {"type": "page", "value": "/pricing"}, {"type": "event", "value": "Signup"}]} : 2 à 8 étapes, 10 entonnoirs maximum par site
DELETE /sites/{site}/funnels/{funnel}	Supprimer un entonnoir
GET /sites/{site}/stats/funnels/{funnel}	Visiteurs à chaque étape dans l'ordre au cours de la même journée, avec la part par rapport à l'étape précédente et à la première étape ; les plages et filtres s'appliquent

Notes

Méthode et chemin	Ce qu'il fait
GET /sites/{site}/notes	Notes sur le graphique ; from et to (AAAA-MM-JJ) restreignent la liste
POST /sites/{site}/notes	{"date": "2026-10-17", "text": "Newsletter envoyée"} : un jour passé ou présent, jusqu'à 200 caractères
DELETE /sites/{site}/notes/{note}	Supprimer une note

Équipe

Méthode et chemin	Ce qu'il fait
GET /team	Personnes invitées sur votre compte, limite de la formule, et équipes auxquelles vous appartenez
POST /team	Inviter : {"email": "[email protected]", "role": "viewer"} (viewer ou manager). L'e-mail d'invitation est envoyé ; la réponse inclut le lien d'invitation
PATCH /team/{member}	Modifier le rôle
DELETE /team/{member}	Supprimer une personne ou une invitation en attente

Jetons

Méthode et chemin	Ce qu'il fait
GET /tokens	Vos jetons, avec leurs capacités et leur dernière utilisation
POST /tokens	{"name": "Rapports", "abilities": ["read"]}. Le jeton en clair est dans la réponse, une seule fois. Un jeton en lecture seule ne peut pas créer de jeton d'écriture
DELETE /tokens/{token}	Révoquer un jeton

Erreurs

Les erreurs utilisent le statut HTTP et un corps avec un code stable :

{ "error": { "code": "account_blocked", "message": "Le compte propriétaire de ce site n'a pas de formule active." } }

Statut	Quand
401	Jeton manquant ou invalide
402	Le compte n'a pas de formule active, a dépassé sa formule ou a atteint une limite
403	Le jeton est en lecture seule et la requête tente une modification
404	Le site, l'objectif ou le membre n'existe pas ou n'est pas accessible à ce jeton
422	Paramètres invalides, par exemple une plage ou une ventilation inconnue
429	Trop de requêtes

Limites

• 120 requêtes par minute par jeton.
• 25 jetons maximum par compte.
• L'API est incluse dans chaque formule et dans l'essai gratuit.