REST API

L'API di Statsdot ti fornisce gli stessi dati della tua dashboard, in formato JSON, e ti permette di gestire siti, obiettivi, il tuo team e i token. Ogni richiesta richiede un token di accesso personale.

Autenticazione

Crea un token nella pagina API e MCP del tuo account. Scegli read only (sola lettura) per script e report, o read and write (lettura e scrittura) se il token deve anche apportare modifiche. Copia il token quando viene mostrato: non verrà mostrato di nuovo.

Invialo nell'intestazione Authorization di ogni richiesta:

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

Un token vede ciò che vede il suo utente: i tuoi siti e i siti dei team a cui appartieni, con il tuo ruolo. Un visualizzatore può leggere un sito del team, un gestore può anche modificarlo e solo il proprietario può eliminarlo.

URL di base e formato

• URL di base: https://statsdot.com/api/v1
• Le richieste e le risposte sono in formato JSON. Le risposte riuscite racchiudono il risultato in data.
• Gli orari sono in formato ISO 8601 in UTC.

Intervalli e filtri

Ogni endpoint delle statistiche accetta gli stessi parametri di query della dashboard:

Parametro	Valori
range	today, 7d, 30d (predefinito), 12m, o un intervallo personalizzato 2026-09-01~2026-09-30 (giorni UTC completi, al massimo due anni)
filters[page]	Solo hit su questo percorso di pagina
filters[entry]	Visite iniziate su questa pagina
filters[source]	Dominio di provenienza, ad esempio google.com; vuoto significa diretto
filters[utm_source], filters[utm_medium], filters[utm_campaign]	Tag della campagna della landing page
filters[country]	Codice paese ISO, ad esempio ES
filters[device]	Desktop, Mobile o Tablet
filters[browser], filters[os]	Come mostrato nella dashboard
filters[event]	Visite che hanno inviato questo evento
filters[goal]	Visite che hanno raggiunto questo ID obiettivo

I visitatori su un intervallo sono visitatori-giorno: Statsdot conta un visitatore una volta al giorno, poiché il codice del visitatore cambia ogni giorno.

Statistiche

Metodo e percorso	Cosa restituisce
GET /sites/{site}/stats/overview	Visitatori, visualizzazioni di pagina, frequenza di rimbalzo e durata della visita (secondi), con il periodo precedente di uguale durata e la variazione in percentuale
GET /sites/{site}/stats/timeseries	Visitatori e visualizzazioni di pagina per giorno, o per mese per intervalli superiori a 90 giorni
GET /sites/{site}/stats/breakdown/{breakdown}	Valori principali di una dimensione per visitatori. breakdown è uno tra pages, entry_pages, exit_pages, referrers, utm_source, utm_medium, utm_campaign, countries, devices, browsers, operating_systems, events, event_labels (con event=Nome). limit da 1 a 100, predefinito 10
GET /sites/{site}/stats/goals	Ogni obiettivo con i visitatori che lo hanno raggiunto, conversioni e tasso di conversione
GET /sites/{site}/stats/realtime	Visitatori negli ultimi cinque minuti
GET /sites/{site}/stats/bots	Richieste di crawler AI nel periodo: totale, per crawler e le pagine lette maggiormente (crawler=openai-gptbot restringe le pagine). Richiede il tracciamento dei crawler AI; i filtri non si applicano

Esempio:

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 }
    ]
  }
}

Account e siti

Metodo e percorso	Cosa fa
GET /account	Il tuo piano, gli eventi utilizzati questo mese e quelli inclusi, i limiti e le capacità del token
GET /sites	Siti che puoi vedere, con il tuo ruolo, le impostazioni e lo snippet di tracciamento
GET /sites/{site}	Un singolo sito
POST /sites	Aggiungi un sito: {"domain": "example.com"}. Aggiungi account_id per aggiungerlo a un account team che gestisci. Si applicano i limiti del piano di quell'account
PATCH /sites/{site}	Modifica weekly_report, public_live, shared (link pubblico di sola lettura), alert_traffic, alert_silence o main_goal_id (un obiettivo del sito, o null)
DELETE /sites/{site}	Elimina un sito di tua proprietà e tutte le sue statistiche

Obiettivi

Metodo e percorso	Cosa fa
GET /sites/{site}/goals	Gli obiettivi di un sito
POST /sites/{site}/goals	{"type": "page", "value": "/thanks"} o {"type": "event", "value": "Signup"}
DELETE /sites/{site}/goals/{goal}	Elimina un obiettivo; le visite rimangono

Funnel

Metodo e percorso	Cosa fa
GET /sites/{site}/funnels	I funnel di un sito
POST /sites/{site}/funnels	{"name": "Sign-up", "steps": [{"type": "page", "value": "/"}, {"type": "page", "value": "/pricing"}, {"type": "event", "value": "Signup"}]}: da 2 a 8 passaggi, al massimo 10 funnel per sito
DELETE /sites/{site}/funnels/{funnel}	Elimina un funnel
GET /sites/{site}/stats/funnels/{funnel}	Visitatori a ogni passaggio in ordine all'interno dello stesso giorno, con la quota del precedente e del primo passaggio; si applicano intervalli e filtri

Note

Metodo e percorso	Cosa fa
GET /sites/{site}/notes	Note sul grafico; from e to (YYYY-MM-DD) restringono l'elenco
POST /sites/{site}/notes	{"date": "2026-10-17", "text": "Newsletter inviata"}: un giorno passato o presente, fino a 200 caratteri
DELETE /sites/{site}/notes/{note}	Elimina una nota

Team

Metodo e percorso	Cosa fa
GET /team	Persone invitate al tuo account, il limite del piano e i team a cui appartieni
POST /team	Invita: {"email": "[email protected]", "role": "viewer"} (viewer o manager). L'email di invito viene inviata; la risposta include il link di invito
PATCH /team/{member}	Modifica il ruolo
DELETE /team/{member}	Rimuovi una persona o un invito in sospeso

Token

Metodo e percorso	Cosa fa
GET /tokens	I tuoi token, con le loro capacità e l'ultimo utilizzo
POST /tokens	{"name": "Reports", "abilities": ["read"]}. Il token in chiaro è nella risposta, una sola volta. Un token di sola lettura non può creare un token di scrittura
DELETE /tokens/{token}	Revoca un token

Errori

Gli errori utilizzano lo stato HTTP e un corpo con un codice stabile:

{ "error": { "code": "account_blocked", "message": "L'account proprietario di questo sito non ha un piano attivo." } }

Stato	Quando
401	Token mancante o non valido
402	L'account non ha un piano attivo, ha superato il piano o ha raggiunto un limite
403	Il token è di sola lettura e la richiesta modifica qualcosa
404	Il sito, l'obiettivo o il membro non esiste o non è disponibile per questo token
422	Parametri non validi, ad esempio un intervallo o un breakdown sconosciuto
429	Troppe richieste

Limiti

• 120 richieste al minuto per token.
• Al massimo 25 token per account.
• L'API è inclusa in ogni piano e nella prova gratuita.