Referencia

Referencia de la API de lectura

Lea las estadísticas de su proyecto desde un servidor, una tarea de almacén de datos o una herramienta de BI. Los endpoints de abajo se generan a partir del propio documento OpenAPI de la API.

URL base y autenticación

Todos los endpoints están bajo https://stg.webmetric.io/v1. Cree una clave de lectura en Configuración y envíela como token bearer en la cabecera Authorization. Una clave de lectura pertenece a un solo proyecto, se muestra una vez y se puede revocar en cualquier momento.

SolicitudShell

curl "https://stg.webmetric.io/v1/read/projects/your_project_id/summary?range=7d" \
  -H "Authorization: Bearer wm_r_your_read_key"

Las claves de lectura son secretas. Llame a la API desde su propio servidor y nunca ponga una clave de lectura en el código de una página ni en un navegador.

La API de lectura solo se incluye en algunos planes, indicados en Planes. En los demás, cada llamada responde 402.

Límites de solicitudes

Cada clave tiene su propia reserva de solicitudes, que se rellena de forma continua. Cada respuesta lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Pasado el límite, la respuesta es 429 y Retry-After indica los segundos que hay que esperar.

Periodos, filtros y páginas

range es un periodo predefinido que termina ahora. from y to aceptan fechas en la zona horaria del proyecto o fechas y horas ISO 8601. Un periodo que llega más atrás de los datos que conserva el proyecto se rechaza con range_exceeds_retention.
Cada dimensión es también un filtro, como device=mobile. Añada device_op=is_not para invertirlo.
Los endpoints de lista devuelven data y next_cursor. Devuelva next_cursor como cursor hasta que sea nulo.

Periodo

Periodo
Parámetro	Tipo	Descripción
`range`consulta	`string`	Un periodo predefinido que termina ahora. Por defecto 7d, acortado a la conservación del proyecto.`24h7d30d90d`
`from`consulta	`string`	Una fecha (AAAA-MM-DD) en la zona horaria del proyecto, o una fecha y hora ISO 8601 con desfase. Requiere to.
`to`consulta	`string`	Incluida cuando es una fecha. Debe ser posterior a from. Una fecha más allá de la conservación del proyecto se rechaza.

Filtros

devicebrowseroscountryregioncitypathreferrerchannelutm_sourceutm_mediumutm_campaignutm_termutm_content

Cada filtro acepta un valor. Un segundo parámetro con el mismo nombre más _op, como device_op, indica cómo se compara el valor. Sin él, el valor debe coincidir exactamente.

Operadores:isis_notcontainsnot_contains

Filtros
Parámetro	Tipo	Descripción
`goal`consulta	`uuid`	Solo los visitantes que completaron este objetivo.

Paginación

Paginación
Parámetro	Tipo	Descripción
`limit`consulta	`integer` de 1 a 1000	Filas por página, de 1 a 1000. Por defecto 100.
`cursor`consulta	`string`	El next_cursor de la página anterior.

Endpoints

Generado a partir del documento OpenAPI de la API, versión 1.0.0: 11 endpoints.

Totales del periodo, con el periodo anterior para comparar

GET/v1/read/projects/{id}/summary

Parámetros
Parámetro	Tipo	Descripción
`id`ruta, obligatorio	`uuid`	El proyecto al que pertenece la clave de lectura.

También acepta: Periodo, Filtros

Campos de la respuesta
Campo	Tipo	Descripción
`pageviews`	`integer`
`sessions`	`integer`
`visitors`	`integer`
`avgDurationSeconds`	`integer`
`bounceRate`	`number` de 0 a 1
`from`	`string`	Inicio del periodo, ISO 8601 en UTC, incluido.
`to`	`string`	Fin del periodo, ISO 8601 en UTC, excluido.
`previous`	`object` o null	El periodo de la misma duración justo anterior a este. Nulo cuando no tuvo sesiones.
`previous.pageviews`	`integer`
`previous.sessions`	`integer`
`previous.visitors`	`integer`
`previous.avgDurationSeconds`	`integer`
`previous.bounceRate`	`number` de 0 a 1

Páginas vistas, visitantes y sesiones por hora o por día, con los intervalos vacíos incluidos

GET/v1/read/projects/{id}/timeseries

Parámetros
Parámetro	Tipo	Descripción
`id`ruta, obligatorio	`uuid`	El proyecto al que pertenece la clave de lectura.

También acepta: Periodo, Filtros

Campos de la respuesta
Campo	Tipo	Descripción
`from`	`string`
`to`	`string`
`timezone`	`string`	La zona horaria IANA del proyecto. Los intervalos empiezan a medianoche, o a la hora en punto, en esa zona.
`bucket`	`string`	`hourdayweek`
`data`	`object[]`
`data[].bucket`	`string`	El inicio del intervalo en ISO 8601 con el desfase de la zona horaria del proyecto, como 2026-09-27T00:00:00+02:00.
`data[].pageviews`	`integer`
`data[].visitors`	`integer`
`data[].sessions`	`integer`

Páginas por páginas vistas

GET/v1/read/projects/{id}/top-paths

Parámetros
Parámetro	Tipo	Descripción
`id`ruta, obligatorio	`uuid`	El proyecto al que pertenece la clave de lectura.

También acepta: Periodo, Filtros, Paginación

Campos de la respuesta
Campo	Tipo	Descripción
`data`	`object[]`
`data[].path`	`string`
`data[].pageviews`	`integer`
`data[].visitors`	`integer`
`next_cursor`	`string` o null	Páselo como cursor para la página siguiente. Nulo en la última página.

Visitantes y páginas vistas por una dimensión

GET/v1/read/projects/{id}/breakdown

Parámetros
Parámetro	Tipo	Descripción
`id`ruta, obligatorio	`uuid`	El proyecto al que pertenece la clave de lectura.
`by`consulta, obligatorio	`string`	`devicebrowseroscountryregioncitypathreferrerchannelutm_sourceutm_mediumutm_campaignutm_termutm_content`

También acepta: Periodo, Filtros, Paginación

Campos de la respuesta
Campo	Tipo	Descripción
`data`	`object[]`
`data[].label`	`string`	El valor de la dimensión. Vacío si no hay ninguno, como en una visita sin referencia.
`data[].country`	`string`	By region or city only: the ISO 3166-1 alpha-2 country the row belongs to.
`data[].visitors`	`integer`
`data[].pageviews`	`integer`
`next_cursor`	`string` o null	Páselo como cursor para la página siguiente. Nulo en la última página.

Eventos personalizados con recuentos y tasa de conversión

GET/v1/read/projects/{id}/events

Parámetros
Parámetro	Tipo	Descripción
`id`ruta, obligatorio	`uuid`	El proyecto al que pertenece la clave de lectura.

También acepta: Periodo, Filtros, Paginación

Campos de la respuesta
Campo	Tipo	Descripción
`data`	`object[]`
`data[].name`	`string`
`data[].count`	`integer`
`data[].visitors`	`integer`
`data[].conversionRate`	`number` de 0 a 1	Visitantes que enviaron el evento, sobre el total de visitantes.
`next_cursor`	`string` o null	Páselo como cursor para la página siguiente. Nulo en la última página.

Páginas en las que empezaron las visitas

GET/v1/read/projects/{id}/entry-pages

Parámetros
Parámetro	Tipo	Descripción
`id`ruta, obligatorio	`uuid`	El proyecto al que pertenece la clave de lectura.

También acepta: Periodo, Filtros, Paginación

Campos de la respuesta
Campo	Tipo	Descripción
`data`	`object[]`
`data[].path`	`string`
`data[].sessions`	`integer`
`data[].visitors`	`integer`
`next_cursor`	`string` o null	Páselo como cursor para la página siguiente. Nulo en la última página.

Páginas en las que terminaron las visitas, con la tasa de salida

GET/v1/read/projects/{id}/exit-pages

Parámetros
Parámetro	Tipo	Descripción
`id`ruta, obligatorio	`uuid`	El proyecto al que pertenece la clave de lectura.

También acepta: Periodo, Filtros, Paginación

Campos de la respuesta
Campo	Tipo	Descripción
`data`	`object[]`
`data[].path`	`string`
`data[].exits`	`integer`
`data[].pageviews`	`integer`
`data[].exitRate`	`number` de 0 a 1	Salidas sobre páginas vistas de la ruta.
`next_cursor`	`string` o null	Páselo como cursor para la página siguiente. Nulo en la última página.

Los embudos del proyecto

GET/v1/read/projects/{id}/funnels

Parámetros
Parámetro	Tipo	Descripción
`id`ruta, obligatorio	`uuid`	El proyecto al que pertenece la clave de lectura.

También acepta: Paginación

Campos de la respuesta
Campo	Tipo	Descripción
`data`	`object[]`
`data[].id`	`uuid`
`data[].name`	`string`
`data[].steps`	`object[]`
`data[].windowHours`	`integer`
`data[].createdAt`	`string`
`next_cursor`	`string` o null	Páselo como cursor para la página siguiente. Nulo en la última página.

Cuántas sesiones llegaron a cada paso

GET/v1/read/projects/{id}/funnels/{funnelId}/report

Parámetros
Parámetro	Tipo	Descripción
`id`ruta, obligatorio	`uuid`	El proyecto al que pertenece la clave de lectura.
`funnelId`ruta, obligatorio	`uuid`

También acepta: Periodo, Filtros

Campos de la respuesta
Campo	Tipo	Descripción
`name`	`string`
`windowHours`	`integer`
`conversionRate`	`number` de 0 a 1
`steps`	`object[]`
`steps[].label`	`string`
`steps[].entered`	`integer`
`steps[].ofStart`	`number` de 0 a 1
`steps[].ofPrevious`	`number` de 0 a 1
`steps[].droppedOff`	`integer`

Conversiones de cada objetivo

GET/v1/read/projects/{id}/goals

Parámetros
Parámetro	Tipo	Descripción
`id`ruta, obligatorio	`uuid`	El proyecto al que pertenece la clave de lectura.

También acepta: Periodo, Filtros, Paginación

Campos de la respuesta
Campo	Tipo	Descripción
`data`	`object[]`
`data[].id`	`uuid`
`data[].name`	`string`
`data[].kind`	`string`	`patheventclick`
`data[].match`	`string`	`exactcontainsstarts_with`
`data[].value`	`string`
`data[].conversions`	`integer`
`data[].converters`	`integer`
`data[].conversionRate`	`number` de 0 a 1
`next_cursor`	`string` o null	Páselo como cursor para la página siguiente. Nulo en la última página.

Un conjunto de datos completo en CSV, nunca truncado

GET/v1/read/projects/{id}/export

Parámetros
Parámetro	Tipo	Descripción
`id`ruta, obligatorio	`uuid`	El proyecto al que pertenece la clave de lectura.
`dataset`consulta	`string`	`pathspagestimeseriescustom-eventsentry-pagesexit-pagesdevicesbrowsersoscountriesregionscitiesreferrerschannelsutm-sourcesutm-mediumsutm-campaigns`

También acepta: Periodo, Filtros

Responde con un archivo CSV que empieza con una fila de cabecera.

Errores

Un error responde con JSON que contiene un code estable y un message. Decida según el código: el mensaje puede cambiar.

Respuestas de error
Estado	Códigos	Descripción
`400`	`invalid_payloadinvalid_rangerange_exceeds_retentioninvalid_cursor`	La solicitud no es válida: un parámetro, el periodo o el cursor.
`401`	`unauthenticatedunknown_keykey_revoked`	Falta la clave, es desconocida o está revocada.
`402`	`upgrade_required`	El plan de la organización no incluye la API de lectura.
`404`	`not_found`	El proyecto no es el de la clave, o el recurso no existe.
`429`	`rate_limited`	Demasiadas solicitudes. Espere los segundos que indica Retry-After.

El documento OpenAPI

El documento legible por máquina está en https://stg.webmetric.io/v1/openapi.json. Impórtelo en un cliente de API o genere a partir de él un cliente con tipos.