Measure the workspace

GET /analytics/overview sums up a time window in a handful of figures. The rest of /analytics/* breaks that summary down by tool, by day and by model, and /insights/* serves the same numbers pre-assembled as the reports behind the "Análisis" panel.

Everything needs analytics:read, and nothing here writes. Email report subscriptions can be listed with GET /insights/schedules, but creating, editing and deleting them isn't available in the API.

The overview

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

What each figure counts:

Both ratios come back as 0 when the denominator is 0, never NaN. ai_agent_id is optional and narrows tool_calls_count to one agent; the other figures are workspace-wide and don't move with it.

The tool leaderboard

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

The window's most-called tools, most to least. ?limit= caps the top: 20 by default, 200 at most. function_name comes back null when a logged call points at a tool that has since been deleted, and the count stays.

Timeseries, resolution times, tokens and latency

Four reads that are narrower than the overview.

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 is one of conversations | messages | tickets_resolved | tool_calls. The response is one point per day; a day with no activity gets no point.

GET /analytics/resolution-times returns count, avg_seconds, p50_seconds and p95_seconds for the whole window. It repeats the same four per resolved_by value (bot, human, auto) under by_resolved_by, so comparing the bot against a person is one call.

GET /analytics/token-usage returns one row per day and model, with prompt_tokens, completion_tokens and total_tokens.

GET /analytics/latency returns operational percentiles (p50_ms, p95_ms, p99_ms, count) by span kind, under kind: agent_turn, tool_call. Its window is short and since starts at the last hour. It's the only read in this chapter that doesn't take from/to.

The panel's reports

/insights/* serves reports that are already assembled, all shaped { data, meta: { window } }. Almost all of them take the same window vocabulary: a rolling preset (?window=7d), the workspace's calendar month, or an explicit from/to range. It's documented in Get started.

A look at the live snapshot:

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": "now" } }
}

meta.window.kind: "instant" is the signal that this report takes no from/to. It describes the present and not a period.

Exporting 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 report.pdf

It's the one endpoint in this chapter that doesn't answer the { data } envelope. It returns raw application/pdf bytes, or the usual error envelope if something fails.

The call is synchronous: it queries the report, writes the narrative with a model and renders, all on the same connection. Treat it as a slow call. If the narrative can't be generated, it still answers 200 with the complete PDF and a note in its place. A 200 doesn't promise there was analysis, only that the figures are there.

Email subscriptions, read only

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
    }
  ]
}

It lists the subscriptions that already exist, the ones that mail a PDF out on a fixed cadence. Creating, editing and deleting one isn't available in the API.