> ## 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. # Peticiones de la aplicación > Devuelve una página del registro de peticiones del sitio de una aplicación, una entrada por petición, con filtros, orden y cursor. Pro y superiores. Devuelve una página del registro de peticiones del sitio de una aplicación, con una entrada por petición: estado, tiempos, origen, dispositivo y el ID de la petición. Úsala para inspeccionar una visita o para encontrar las peticiones exactas detrás de un número en [Errores](https://docs.vertracloud.app/es-es/web-analytics/errors.md) o [Rendimiento](https://docs.vertracloud.app/es-es/web-analytics/performance.md). Acepta los mismos filtros que las otras rutas de analytics y pagina con cursor. Son los datos de [Peticiones](https://docs.vertracloud.app/es-es/web-analytics/requests.md) y **requiere un plan con el registro de peticiones (Pro y superiores)**. **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. **cursor** `string` `cursor` opaco de la página anterior. Envíalo con la misma ventana, los mismos filtros y el mismo orden; cualquier otro cursor se rechaza con `VALIDATION_ERROR`. **order** `string` (default: desc) Orden por hora: `desc` (más nuevas primero) o `asc`. Por defecto `desc`. **limit** `integer` (default: 50) Peticiones por página, de 1 a 100. Por defecto 50. 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. ### Paginación Lee la primera página sin `cursor`. Mientras la respuesta tenga `cursor`, llama de nuevo con los mismos `start`, `end`, filtros y `order` más ese `cursor`. Fija `start` y `end` durante todo el recorrido: con el `end` por defecto (ahora) la ventana se mueve entre llamadas. La lectura termina cuando `cursor` es `null`. ### 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. **order** `string` Orden de la página: `asc` o `desc`. **requests** `object[]` Las peticiones de la página, en el orden pedido. **cursor** `string | null` Reenvíalo como `cursor` para obtener la siguiente página, con la misma ventana, los mismos filtros y el mismo orden. `null` en la última página. Campos de cada petición: **time** `string` Cuándo llegó la petición (ISO 8601). **request\_id** `string` Identificador de la petición. Cítalo cuando contactes con soporte. **host** `string` Hostname que pidió el visitante. **path** `string` Ruta de la petición. **query** `string` Query string sin el `?` inicial; vacía cuando la petición no tenía. Puede llevar tokens: trátala como dato sensible. **method** `string` Método HTTP. **protocol** `string` Versión de HTTP. **status** `integer` Estado HTTP que recibió el visitante. **container\_status** `integer | null` Estado HTTP que respondió tu aplicación; `null` cuando la petición no llegó a ella (respondida por la caché o por la borde). **edge\_time\_ms** `number` Todo el tiempo que esperó el visitante el primer byte, en milisegundos. **container\_time\_ms** `number | null` Tiempo que tardó tu aplicación en responder, en milisegundos; `null` cuando la petición no llegó a ella. **ip** `string` Dirección IP del visitante. Dato personal: trátala como sensible. **asn** `integer` Número del sistema autónomo de la red del visitante. **asn\_name** `string` Nombre de la red del visitante. **country** `string` País del visitante. **edge\_location** `string` Ubicación de borde que respondió. **referer** `string` Host del referer; `(none)` es una visita directa. **referer\_url** `string | null` URL completa del referer; `null` cuando la petición no tenía. **device** `string` Tipo de dispositivo. **os** `string` Sistema operativo. **browser** `string` Navegador. **bot** `string` Categoría de un bot verificado; `(none)` en otro caso. **content\_type** `string` Tipo de contenido respondido. **cache\_status** `string` Si la borde respondió desde su caché. ```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, "order": "desc", "requests": [ { "time": "2026-11-03T17:58:41Z", "request_id": "req_8f3a2c71d94b", "host": "www.example.com", "path": "/api/checkout", "query": "cart=9f2c", "method": "POST", "protocol": "HTTP/2", "status": 502, "container_status": 502, "edge_time_ms": 1840, "container_time_ms": 1812, "ip": "203.0.113.24", "asn": 28573, "asn_name": "CLARO S.A.", "country": "BR", "edge_location": "GRU", "referer": "www.example.com", "referer_url": "https://www.example.com/cart", "device": "mobile", "os": "Android", "browser": "Chrome", "bot": "(none)", "content_type": "json", "cache_status": "dynamic" }, { "time": "2026-11-03T17:58:12Z", "request_id": "req_1b7e40c9a2d5", "host": "www.example.com", "path": "/pricing", "query": "", "method": "GET", "protocol": "HTTP/2", "status": 200, "container_status": null, "edge_time_ms": 38, "container_time_ms": null, "ip": "203.0.113.24", "asn": 28573, "asn_name": "CLARO S.A.", "country": "BR", "edge_location": "GRU", "referer": "google.com", "referer_url": "https://www.google.com/", "device": "mobile", "os": "Android", "browser": "Chrome", "bot": "(none)", "content_type": "html", "cache_status": "hit" } ], "cursor": "c_7Qm2Xk9pLw3RzT5v" } } ``` ```bash cURL theme={null} curl -G "https://api.vertracloud.app/v1/apps/app-abc123def456/analytics/requests" \ -H "Authorization: Bearer YOUR_TOKEN" \ --data-urlencode "start=2026-11-03T17:00:00Z" \ --data-urlencode "end=2026-11-03T18:00:00Z" \ --data-urlencode "status=5xx" \ --data-urlencode "path=/api" \ --data-urlencode "order=desc" \ --data-urlencode "limit=50" ``` ### 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. * **Pro y superiores.** En Starter la llamada falla con `PLAN_DOES_NOT_SUPPORT_WEB_ANALYTICS_REQUESTS`. El flag del plan es `features.web_analytics_requests` en [Listar planes](https://docs.vertracloud.app/es-es/api-reference/endpoint/plans/list.md). * **Muestreo.** Con tráfico alto el registro es una **muestra** de las peticiones, no todas: `sampled` viene `true` y una petición concreta puede no estar. * **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. | | 403 | `PLAN_DOES_NOT_SUPPORT_WEB_ANALYTICS_REQUESTS` | El plan no incluye el registro de peticiones (Starter). Pasa a Pro o superior. | | 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. | | 400 | `INVALID_RANGE` | `start` es posterior a `end`, `end` está en el futuro o la ventana supera los 30 días. | | 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. | | 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.