> ## Documentation Index > Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt > Use this file to discover all available pages before exploring further. # Tráfico de la aplicación > Devuelve el tráfico del sitio de una aplicación: totales, serie temporal y breakdowns por país, ruta y dispositivo, con filtros y comparación. Devuelve el tráfico del sitio de una aplicación: totales, una serie temporal y los valores más frecuentes de cada dimensión (países, rutas, dispositivos, navegadores, referers...). Todo filtro vale para todas las partes de la respuesta, así que una llamada da los números detrás de un clic en la subpestaña Tráfico. Son los mismos datos de [Tráfico y filtros](https://docs.vertracloud.app/es-es/web-analytics/traffic.md), del [Resumen](https://docs.vertracloud.app/es-es/web-analytics/summary.md) y de [Comparar](https://docs.vertracloud.app/es-es/web-analytics/compare.md). **id** `string` *required* El ID de la aplicación. Si pertenece a un workspace, pasa su ID en el query parameter `workspace_id`. **workspace\_id** `string` Si la aplicación pertenece a un workspace, el ID del workspace. Obligatorio para miembros del workspace que actúan sobre una aplicación que no es suya. **start** `string` Inicio de la ventana (ISO 8601). Por defecto: 24 horas antes de `end`. **end** `string` Fin de la ventana (ISO 8601). Por defecto: ahora. No puede estar en el futuro. **compare** `boolean` (default: false) Envía también el período anterior, de la misma duración y justo antes de la ventana, en `previous`. Por defecto `false`. **compare\_start** `string` Inicio del periodo a comparar (ISO 8601). El periodo comparado tiene la misma duración que la ventana (`end` menos `start`) y empieza aquí; `previous.start` y `previous.end` en la respuesta muestran cuál fue. Implica `compare=true` y no se puede enviar con `compare=false`. Sin él, `compare=true` compara con el periodo justo antes de la ventana. **breakdowns** `string` Dimensiones separadas por coma para desglosar, como `country,path`. Omitido: todos los recortes. Vacío (`breakdowns=`): ninguno, solo el resumen y la serie, con respuesta más rápida. Nombre desconocido: `VALIDATION_ERROR`. Las dimensiones están listadas en Filtros. **limit** `integer` (default: 10) Entradas por breakdown, de 1 a 25. Por defecto 10. La ventana dura como máximo 30 días y no puede empezar antes del historial del plan (7 o 30 días, ver [Planes y límites](https://docs.vertracloud.app/es-es/plans-and-limits.md)). ### Filtros Cada dimensión de abajo también es un filtro, y todos se pueden combinar: cada uno restringe todas las partes de la respuesta. Cada filtro recibe **un valor**, exactamente como aparece en una entrada de breakdown o en una petición del registro, así que un valor leído en una respuesta se puede reenviar sin cambios. Envía `(none)` para quedarte solo con las peticiones que no tienen nada en la dimensión. **country** `string` País del visitante, ISO 3166-1 alfa-2 (`BR`). **edge\_location** `string` Código IATA de la ubicación de borde que respondió (`GRU`). **host** `string` Hostname que pidió el visitante: el subdominio de la aplicación o uno de sus dominios. Solo se aceptan hosts de la aplicación. **path** `string` Ruta de la petición, sin la query string. Es un prefijo: `/api` coincide con `/api`, `/api/users` y `/apix`. **method** `string` Método HTTP (`GET`, `POST`...). **status** `string` Estado HTTP que recibió el visitante (`404`), o una clase: `2xx`, `3xx`, `4xx` o `5xx`. **protocol** `string` Versión de HTTP: `HTTP/1.1`, `HTTP/2` o `HTTP/3`. **device** `string` Tipo de dispositivo: `desktop`, `mobile` o `tablet`. **os** `string` Sistema operativo del visitante (`Windows`, `iOS`...). **browser** `string` Navegador del visitante (`Chrome`, `Safari`...). **referer** `string` Host de la página que llevó a la petición (`google.com`). `(none)` es una visita directa, sin referer. **asn** `string` Número del sistema autónomo de la red del visitante (`28573`). **ip** `string` Dirección IP del visitante. **content\_type** `string` Tipo de contenido respondido (`html`, `json`, `css`, `js`, `png`...). **cache\_status** `string` Si la borde respondió desde su caché: `hit`, `miss`, `dynamic`, `bypass`, `expired`, `revalidated`... **bot** `string` Categoría de un bot verificado (`Search Engine Crawler`...). `(none)` es un visitante que no es un bot verificado. ### Respuesta **response** `object` **Toggle object** **start** `string` Inicio de la ventana realmente leída (ISO 8601). Puede estar redondeado respecto al que enviaste. **end** `string` Fin de la ventana realmente leída (ISO 8601). **hosts** `string[]` Hostnames que se leyeron: el subdominio de la aplicación y sus dominios activos. **web\_published** `boolean` `false` cuando la aplicación no tiene sitio publicado. La respuesta es entonces un estado vacío, no un error: `hosts` viene vacío y los datos también. **sampled** `boolean` `true` cuando el tráfico es lo bastante alto como para que los números se estimen a partir de una muestra. **stale** `boolean` `true` cuando no se pudieron leer los datos más recientes y esta es una respuesta anterior. Ver `generated_at`. **generated\_at** `string` Cuándo se leyeron los datos (ISO 8601). **history\_days** `integer` Cuántos días hacia atrás puede leer el plan del dueño de la aplicación. **interval** `string` Tamaño de cada punto de `series`: `1m`, `5m`, `15m` o `1h`. La API lo elige según la duración de la ventana: cuanto más corta, más finos los puntos. **summary** `object | null` Totales de la ventana. `null` cuando no hubo peticiones en la ventana. **series** `object[]` Puntos de la serie temporal; `time` es el inicio de cada punto. **previous** `object | null` El período anterior, solo con `compare=true`; si no, `null`. Tiene `start`, `end`, un `summary` (`null` cuando no hubo peticiones en él) y una `series` con el mismo `interval` y el mismo número de puntos que la actual, en el mismo orden. **breakdowns** `object` Entradas más frecuentes de cada dimensión, mayor `requests` primero: solo las dimensiones pedidas en `breakdowns`, o todas si se omite. El filtro enviado vale para todas. **Toggle entry** **value** `string` Valor de la dimensión; envíalo como el filtro del mismo nombre. `(none)` significa que la petición no tenía valor. **label** `string | null` Nombre legible cuando `value` es un código (el nombre de la red de un `asn`); `null` en otro caso. **requests** `integer` Peticiones con este valor. **visits** `integer` Visitas a páginas con este valor. **bytes** `integer` Bytes enviados a los visitantes. Campos de `summary`, y de los mismos totales en `previous.summary`: **requests** `integer` Peticiones respondidas. **visits** `integer` Visitas a páginas: peticiones que inician una visita (una página abierta directamente o desde otro sitio). **bytes** `integer` Bytes enviados a los visitantes. **errors\_4xx** `integer` Peticiones respondidas con estado 4xx. **errors\_5xx** `integer` Peticiones respondidas con estado 5xx. **error\_rate\_4xx** `number` `errors_4xx / requests`, de 0 a 1. **error\_rate\_5xx** `number` `errors_5xx / requests`, de 0 a 1. **edge\_time\_p95\_ms** `number` Percentil 95 del tiempo de borde (cuánto esperó el visitante el primer byte), en milisegundos. Es el único número de velocidad que reciben todos los planes. Campos de cada punto de `series` (y de `previous.series`): `time`, `requests`, `visits`, `bytes`, `errors_4xx` y `errors_5xx`, con el mismo significado que en `summary`. ```json Response theme={null} { "response": { "start": "2026-11-02T18:00:00Z", "end": "2026-11-03T18:00:00Z", "hosts": [ "my-app.vertraweb.app", "www.example.com" ], "web_published": true, "sampled": false, "stale": false, "generated_at": "2026-11-03T18:01:12Z", "history_days": 7, "interval": "1h", "summary": { "requests": 18420, "visits": 6310, "bytes": 412884113, "errors_4xx": 214, "errors_5xx": 9, "error_rate_4xx": 0.0116, "error_rate_5xx": 0.0005, "edge_time_p95_ms": 412 }, "series": [ { "time": "2026-11-02T18:00:00Z", "requests": 702, "visits": 240, "bytes": 15331004, "errors_4xx": 8, "errors_5xx": 0 }, { "time": "2026-11-02T19:00:00Z", "requests": 731, "visits": 251, "bytes": 16120987, "errors_4xx": 11, "errors_5xx": 1 } ], "previous": { "start": "2026-11-01T18:00:00Z", "end": "2026-11-02T18:00:00Z", "summary": { "requests": 16990, "visits": 5802, "bytes": 380112007, "errors_4xx": 190, "errors_5xx": 4, "error_rate_4xx": 0.0112, "error_rate_5xx": 0.0002, "edge_time_p95_ms": 455 }, "series": [ { "time": "2026-11-01T18:00:00Z", "requests": 650, "visits": 222, "bytes": 14100222, "errors_4xx": 7, "errors_5xx": 0 } ] }, "breakdowns": { "country": [ { "value": "BR", "label": null, "requests": 14210, "visits": 4902, "bytes": 318400221 }, { "value": "US", "label": null, "requests": 2105, "visits": 760, "bytes": 48112003 }, { "value": "PT", "label": null, "requests": 611, "visits": 204, "bytes": 13920110 } ], "path": [ { "value": "/", "label": null, "requests": 5210, "visits": 4100, "bytes": 90211003 }, { "value": "/pricing", "label": null, "requests": 1902, "visits": 1180, "bytes": 41230991 } ], "referer": [ { "value": "(none)", "label": null, "requests": 9120, "visits": 3300, "bytes": 201004112 }, { "value": "google.com", "label": null, "requests": 4410, "visits": 1890, "bytes": 98114003 } ], "asn": [ { "value": "28573", "label": "CLARO S.A.", "requests": 3300, "visits": 1100, "bytes": 70112008 } ], "cache_status": [ { "value": "hit", "label": null, "requests": 13011, "visits": 0, "bytes": 301100001 }, { "value": "dynamic", "label": null, "requests": 4100, "visits": 0, "bytes": 90113002 } ] } } } ``` ```bash cURL theme={null} curl -G "https://api.vertracloud.app/v1/apps/app-abc123def456/analytics" \ -H "Authorization: Bearer YOUR_TOKEN" \ --data-urlencode "start=2026-11-02T18:00:00Z" \ --data-urlencode "end=2026-11-03T18:00:00Z" \ --data-urlencode "compare=true" \ --data-urlencode "country=BR" \ --data-urlencode "status=2xx" \ --data-urlencode "path=/api" \ --data-urlencode "breakdowns=country,path,referer" \ --data-urlencode "limit=5" ``` ### Notas * Requiere el scope `apps:read` cuando se llama con una API key. Los miembros de un workspace necesitan permiso para leer la aplicación. * Disponible en todos los planes. Una cuenta sin plan activo recibe `PLAN_REQUIRED`. * **Muestreo.** Con tráfico alto los números se estiman a partir de una muestra y `sampled` viene `true`. Ver [Muestreo y retraso](https://docs.vertracloud.app/es-es/web-analytics/sampling-and-delay.md). * **Retraso.** Los datos se actualizan cada unos 5 minutos, así que las peticiones más nuevas pueden tardar unos minutos en aparecer. Si los datos más recientes no se pueden leer ahora, puede volver una respuesta anterior con `stale: true` (revisa `generated_at`); de lo contrario, la llamada falla con `ANALYTICS_BUSY`. * **Privacidad.** Vertra Cloud no guarda nada de los visitantes; guarda solo totales por app (recuentos, visitas, bytes, tasas de error y tiempos de respuesta) hasta 31 días, borrados con la app. No se guarda ninguna IP, ruta, query string ni user agent. `ip` y `query` vuelven sin máscara; enmascararlos es decisión del cliente que los muestra. Ver [Privacidad](https://docs.vertracloud.app/es-es/web-analytics/privacy.md). ### Respuestas de error | Status | Código | Cuándo | | - | - | - | | 401 | `AUTH_TOKEN_MISSING` / `API_KEY_INVALID` / `SESSION_REVOKED` | Falta el header `Authorization`, la API key es inválida o la sesión del panel fue revocada. | | 403 | `API_KEY_IP_DENIED` / `API_KEY_SCOPE_DENIED` | La API key se usa desde una IP fuera de su lista permitida, o no tiene el scope `apps:read`. | | 403 | `ACCESS_DENIED` | La aplicación pertenece a otra cuenta, o no tienes el permiso de workspace para leerla. | | 403 | `PLAN_REQUIRED` | La cuenta no tiene plan activo. | | 404 | `APP_NOT_FOUND` | La aplicación no existe. | | 400 | `VALIDATION_ERROR` | Un parámetro falló la validación, como `limit` fuera de rango, un `cursor` inválido o una fecha `start`/`end` mal formada; `details.path` nombra el campo. También cuando `compare_start` está mal formado o se envía con `compare=false`. | | 400 | `INVALID_RANGE` | `start` es posterior a `end`, `end` está en el futuro o la ventana supera los 30 días. También cuando el periodo que empieza en `compare_start` termina después de `start`, lo que solaparía la ventana. | | 400 | `ANALYTICS_RANGE_EXCEEDS_PLAN` | `start` es anterior a lo que el plan puede leer. `details.history_days` trae el límite en días y `details.earliest` el `start` más antiguo aceptado ahora. También cuando `compare_start` es anterior a lo que el plan puede leer. | | 429 | `RATE_LIMIT_EXCEEDED` | Demasiadas consultas seguidas. `details.retry_after` indica la espera en segundos; la cabecera `Retry-After` viene siempre con ella. | | 503 | `ANALYTICS_BUSY` | Momento de alta demanda y sin respuesta reciente disponible para la consulta. Espera `details.retry_after` segundos e inténtalo de nuevo. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.