API REST

La API de Statsdot te ofrece los mismos datos que tu panel, en formato JSON, y te permite gestionar sitios, objetivos, tu equipo y tokens. Cada solicitud requiere un token de acceso personal.

Autenticación

Crea un token en la página API y MCP de tu cuenta. Elige solo lectura para scripts e informes, o lectura y escritura si el token también debe poder realizar cambios. Copia el token en el momento en que se muestra: no se volverá a mostrar.

Envíalo en la cabecera Authorization de cada solicitud:

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

Un token ve lo que ve su usuario: tus propios sitios y los sitios de los equipos a los que perteneces, con tu rol en ellos. Un lector puede leer un sitio de equipo, un gestor también puede modificarlo, y solo el propietario puede eliminarlo.

URL base y formato

• URL base: https://statsdot.com/api/v1
• Las solicitudes y respuestas son en formato JSON. Las respuestas exitosas envuelven el resultado en data.
• Las horas siguen el formato ISO 8601 en UTC.

Rangos y filtros

Cada endpoint de estadísticas acepta los mismos parámetros de consulta que el panel:

Parámetro	Valores
range	today, 7d, 30d (predeterminado), 12m, o un rango personalizado 2026-09-01~2026-09-30 (días UTC completos, como máximo dos años)
filters[page]	Solo visitas a esta ruta de página
filters[entry]	Visitas que comenzaron en esta página
filters[source]	Dominio de procedencia, por ejemplo google.com; vacío significa directo
filters[utm_source], filters[utm_medium], filters[utm_campaign]	Etiquetas de campaña de la página de destino
filters[country]	Código de país ISO, por ejemplo ES
filters[device]	Desktop, Mobile o Tablet
filters[browser], filters[os]	Tal como se muestran en el panel
filters[event]	Visitas que enviaron este evento
filters[goal]	Visitas que alcanzaron este ID de objetivo

Los visitantes en un rango se calculan como visitante-días: Statsdot cuenta a un visitante una vez por día, ya que el código de visitante cambia cada día.

Estadísticas

Método y ruta	Lo que devuelve
GET /sites/{site}/stats/overview	Visitantes, páginas vistas, tasa de rebote y duración de la visita (en segundos), junto con el periodo anterior de la misma longitud y el cambio porcentual
GET /sites/{site}/stats/timeseries	Visitantes y páginas vistas por día, o por mes para rangos superiores a 90 días
GET /sites/{site}/stats/breakdown/{breakdown}	Valores principales de una dimensión ordenados por visitantes. breakdown puede ser pages, entry_pages, exit_pages, referrers, utm_source, utm_medium, utm_campaign, countries, devices, browsers, operating_systems, events, event_labels (con event=Name). limit de 1 a 100, predeterminado 10
GET /sites/{site}/stats/goals	Cada objetivo con los visitantes que lo alcanzaron, conversiones y tasa de conversión
GET /sites/{site}/stats/realtime	Visitantes en los últimos cinco minutos
GET /sites/{site}/stats/bots	Solicitudes de rastreadores de IA en el periodo: total, por rastreador y las páginas que leen con más frecuencia (crawler=openai-gptbot acota las páginas). Requiere el seguimiento de rastreadores de IA; los filtros no se aplican

Ejemplo:

curl "https://statsdot.com/api/v1/sites/42/stats/breakdown/referrers?range=7d&limit=5" \
  -H "Authorization: Bearer 12|tu-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 }
    ]
  }
}

Cuenta y sitios

Método y ruta	Lo que hace
GET /account	Tu plan, eventos consumidos este mes y incluidos, límites y las capacidades del token
GET /sites	Sitios que puedes ver, con tu rol, configuración y código de seguimiento
GET /sites/{site}	Un sitio
POST /sites	Añade un sitio: {"domain": "example.com"}. Añade account_id para agregarlo a una cuenta de equipo que gestiones. Se aplican los límites del plan de esa cuenta
PATCH /sites/{site}	Modifica weekly_report, public_live, shared (enlace público de solo lectura), alert_traffic, alert_silence o main_goal_id (un objetivo del sitio, o null)
DELETE /sites/{site}	Elimina un sitio de tu propiedad y todas sus estadísticas

Objetivos

Método y ruta	Lo que hace
GET /sites/{site}/goals	Los objetivos de un sitio
POST /sites/{site}/goals	{"type": "page", "value": "/thanks"} o {"type": "event", "value": "Signup"}
DELETE /sites/{site}/goals/{goal}	Elimina un objetivo; las visitas se conservan

Embudos

Método y ruta	Lo que hace
GET /sites/{site}/funnels	Los embudos de un sitio
POST /sites/{site}/funnels	{"name": "Sign-up", "steps": [{"type": "page", "value": "/"}, {"type": "page", "value": "/pricing"}, {"type": "event", "value": "Signup"}]}: de 2 a 8 pasos, un máximo de 10 embudos por sitio
DELETE /sites/{site}/funnels/{funnel}	Elimina un embudo
GET /sites/{site}/stats/funnels/{funnel}	Visitantes en cada paso de forma ordenada dentro del mismo día, con el porcentaje respecto al paso anterior y al primer paso; se aplican rangos y filtros

Notas

Método y ruta	Lo que hace
GET /sites/{site}/notes	Notas en la gráfica; from y to (AAAA-MM-DD) acotan la lista
POST /sites/{site}/notes	{"date": "2026-10-17", "text": "Newsletter sent"}: un día pasado o actual, hasta 200 caracteres
DELETE /sites/{site}/notes/{note}	Elimina una nota

Equipo

Método y ruta	Lo que hace
GET /team	Personas invitadas a tu cuenta, el límite del plan y los equipos a los que perteneces
POST /team	Invitar: {"email": "[email protected]", "role": "viewer"} (viewer o manager). Se envía el correo electrónico de invitación; la respuesta incluye el enlace de invitación
PATCH /team/{member}	Cambia el rol
DELETE /team/{member}	Elimina a una persona o una invitación pendiente

Tokens

Método y ruta	Lo que hace
GET /tokens	Tus tokens, con sus capacidades y último uso
POST /tokens	{"name": "Reports", "abilities": ["read"]}. El token en texto plano aparece en la respuesta, una sola vez. Un token de lectura no puede crear un token de escritura
DELETE /tokens/{token}	Revoca un token

Errores

Los errores utilizan el estado HTTP y un cuerpo con un código estable:

{ "error": { "code": "account_blocked", "message": "The account that owns this site has no active plan." } }

Estado	Cuándo
401	Falta el token o no es válido
402	La cuenta no tiene ningún plan activo, ha superado su plan o ha alcanzado un límite
403	El token es de solo lectura y la solicitud realiza cambios
404	El sitio, objetivo o miembro no existe o no está disponible para este token
422	Parámetros no válidos, por ejemplo, un rango o desglose desconocido
429	Demasiadas solicitudes

Límites

• 120 solicitudes por minuto por token.
• Un máximo de 25 tokens por cuenta.
• La API está incluida en todos los planes y en la prueba gratuita.