Peticiones de la aplicación

GET

apps

{id}

analytics

requests

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"

{
  "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"
  }
}

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 o Rendimiento. Acepta los mismos filtros que las otras rutas de analytics y pagina con cursor. Son los datos de Peticiones y requiere un plan con el registro de peticiones (Pro y superiores).

string

requerido

El ID de la aplicación. Si pertenece a un workspace, pasa su ID en el query parameter 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.

string

Inicio de la ventana (ISO 8601). Por defecto: 24 horas antes de end.

string

Fin de la ventana (ISO 8601). Por defecto: ahora. No puede estar en el futuro.

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.

string

predeterminado:"desc"

Orden por hora: desc (más nuevas primero) o asc. Por defecto desc.

integer

predeterminado:"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).

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.

string

País del visitante, ISO 3166-1 alfa-2 (BR).

string

Código IATA de la ubicación de borde que respondió (GRU).

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.

string

Ruta de la petición, sin la query string. Es un prefijo: /api coincide con /api, /api/users y /apix.

string

Método HTTP (GET, POST…).

string

Estado HTTP que recibió el visitante (404), o una clase: 2xx, 3xx, 4xx o 5xx.

string

Versión de HTTP: HTTP/1.1, HTTP/2 o HTTP/3.

string

Tipo de dispositivo: desktop, mobile o tablet.

string

Sistema operativo del visitante (Windows, iOS…).

string

Navegador del visitante (Chrome, Safari…).

string

Host de la página que llevó a la petición (google.com). (none) es una visita directa, sin referer.

string

Número del sistema autónomo de la red del visitante (28573).

string

Dirección IP del visitante.

string

Tipo de contenido respondido (html, json, css, js, png…).

string

Si la borde respondió desde su caché: hit, miss, dynamic, bypass, expired, revalidated…

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

object

Mostrar Toggle object

string

Inicio de la ventana realmente leída (ISO 8601). Puede estar redondeado respecto al que enviaste.

string

Fin de la ventana realmente leída (ISO 8601).

string[]

Hostnames que se leyeron: el subdominio de la aplicación y sus dominios activos.

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.

boolean

true cuando el tráfico es lo bastante alto como para que los números se estimen a partir de una muestra.

boolean

true cuando no se pudieron leer los datos más recientes y esta es una respuesta anterior. Ver generated_at.

string

Cuándo se leyeron los datos (ISO 8601).

integer

Cuántos días hacia atrás puede leer el plan del dueño de la aplicación.

string

Orden de la página: asc o desc.

object[]

Las peticiones de la página, en el orden pedido.

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:

string

Cuándo llegó la petición (ISO 8601).

string

Identificador de la petición. Cítalo cuando contactes con soporte.

string

Hostname que pidió el visitante.

string

Ruta de la petición.

string

Query string sin el ? inicial; vacía cuando la petición no tenía. Puede llevar tokens: trátala como dato sensible.

string

Método HTTP.

string

Versión de HTTP.

integer

Estado HTTP que recibió el visitante.

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).

number

Todo el tiempo que esperó el visitante el primer byte, en milisegundos.

number | null

Tiempo que tardó tu aplicación en responder, en milisegundos; null cuando la petición no llegó a ella.

string

Dirección IP del visitante. Dato personal: trátala como sensible.

integer

Número del sistema autónomo de la red del visitante.

string

Nombre de la red del visitante.

string

País del visitante.

string

Ubicación de borde que respondió.

string

Host del referer; (none) es una visita directa.

string | null

URL completa del referer; null cuando la petición no tenía.

string

Tipo de dispositivo.

string

Sistema operativo.

string

Navegador.

string

Categoría de un bot verificado; (none) en otro caso.

string

Tipo de contenido respondido.

string

Si la borde respondió desde su caché.

{
  "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"
  }
}

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.
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.

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.

Última modificación el 3 de noviembre de 2026

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"

{
  "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"
  }
}

Visión general

Endpoints

Peticiones de la aplicación

Filtros

Paginación

Respuesta

Notas

Respuestas de error

​Filtros

​Paginación

​Respuesta

​Notas

​Respuestas de error

Filtros

Paginación

Respuesta

Notas

Respuestas de error