Medir el workspace

GET /analytics/overview resume una ventana de tiempo en un puñado de cifras. El resto de /analytics/* abre ese resumen por herramienta, por día y por modelo, y /insights/* entrega los mismos números ya armados como reportes del panel «Análisis».

Todo pide analytics:read y nada de esto escribe. Las suscripciones de reporte por correo se pueden listar con GET /insights/schedules, pero crearlas, editarlas y borrarlas no está disponible en la API.

El resumen general

curl "https://api.vitrinadev.com/api/v1/analytics/overview?from=2026-09-01T00:00:00.000Z&to=2026-09-22T00:00:00.000Z" \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": {
    "conversations_count": 182,
    "messages_count": 940,
    "tickets_resolved_count": 140,
    "resolved_by_bot": 96,
    "resolved_by_human": 40,
    "resolved_by_auto": 4,
    "tool_calls_count": 310,
    "distinct_contacts_count": 165,
    "bot_resolution_rate": 0.6857,
    "tool_use_per_message": 0.3298
  },
  "meta": { "from": "2026-09-01T00:00:00.000Z", "to": "2026-09-22T00:00:00.000Z" }
}

Qué cuenta cada cifra:

Las dos razones dan 0 cuando el denominador es 0, nunca NaN. ai_agent_id es opcional y acota tool_calls_count a un agente puntual; las demás cifras son del workspace completo y no cambian con él.

El ranking de herramientas

curl "https://api.vitrinadev.com/api/v1/analytics/tools?from=2026-09-01T00:00:00.000Z&to=2026-09-22T00:00:00.000Z" \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": [
    { "function_id": "b6b6b6b6-1000-4000-8000-000000000001", "function_name": "book_appointment", "call_count": 214 },
    { "function_id": "b6b6b6b6-1000-4000-8000-000000000002", "function_name": "get_weather", "call_count": 58 }
  ],
  "meta": { "total": 2, "from": "2026-09-01T00:00:00.000Z", "to": "2026-09-22T00:00:00.000Z" }
}

Trae las herramientas más llamadas de la ventana, de más a menos. ?limit= acota el top: 20 por defecto, 200 como máximo. function_name llega en null cuando la llamada quedó registrada contra una herramienta que ya se borró, y el conteo sigue ahí.

Serie de tiempo, tiempos de resolución, tokens y latencia

Cuatro lecturas más angostas que el resumen.

curl "https://api.vitrinadev.com/api/v1/analytics/timeseries?from=2026-09-15T00:00:00.000Z&to=2026-09-22T00:00:00.000Z&metric=conversations" \
  -H "Authorization: Bearer $VITRINA_KEY"

metric es uno de conversations | messages | tickets_resolved | tool_calls. La respuesta trae un punto por día; un día sin actividad no aparece en la serie.

GET /analytics/resolution-times trae count, avg_seconds, p50_seconds y p95_seconds para la ventana completa. Repite el mismo cuarteto por cada valor de resolved_by (bot, human, auto) en by_resolved_by, así que comparar al bot con una persona es una sola llamada.

GET /analytics/token-usage trae una fila por día y modelo, con prompt_tokens, completion_tokens y total_tokens.

GET /analytics/latency trae percentiles operacionales (p50_ms, p95_ms, p99_ms, count) por tipo de tramo, en kind: agent_turn, tool_call. Su ventana es corta y since parte en la última hora. Es la única lectura del capítulo que no toma from/to.

Los reportes del panel

/insights/* entrega reportes ya armados, todos con la forma { data, meta: { window } }. Casi todos aceptan el mismo vocabulario de ventana: un preset rodante (?window=7d), un mes calendario del workspace, o un rango explícito from/to. Está documentado en Empezar.

Un vistazo a la foto instantánea:

curl https://api.vitrinadev.com/api/v1/insights/overview/live \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": { "open": 14, "unattended": 0, "unassigned": 1, "pending": 0, "agents_online": 1, "agents_busy": 0, "agents_offline": 4 },
  "meta": { "window": { "kind": "instant", "at": "2026-09-22T16:38:43.071Z", "label": "ahora" } }
}

meta.window.kind: "instant" avisa que este reporte no acepta from/to. Describe el presente y no un período.

Exportar a PDF

curl -X POST https://api.vitrinadev.com/api/v1/insights/generate-pdf \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "report": "conversations", "range": { "preset": "7d" } }' \
  --output reporte.pdf

Es el único endpoint del capítulo que no responde el sobre { data }. Devuelve bytes application/pdf, o el sobre de error de siempre si algo falla.

La llamada es síncrona: consulta el reporte, redacta el narrativo con un modelo y renderiza, todo en la misma conexión. Trátala como una llamada lenta. Si el narrativo no se puede generar, igual responde 200 con el PDF completo y una nota en su lugar. Un 200 no promete que hubo análisis, solo que las cifras están.

Suscripciones por correo, de solo lectura

curl https://api.vitrinadev.com/api/v1/insights/schedules \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": [
    {
      "id": "cccccccc-2000-4000-8000-000000000001",
      "report_type": "conversations",
      "range_preset": "7d",
      "cadence": "weekly",
      "recipients": ["[email protected]"],
      "next_run_at": "2026-09-29T09:00:00.000Z",
      "enabled": true
    }
  ]
}

Lista las suscripciones que ya existen, las que mandan un PDF por correo en una cadencia fija. Crear, editar y borrar una no está disponible en la API.