Analytics

The Analytics API provides pre-aggregated metrics and raw report generation for conversations, agents, telephony usage, and costs.

Base paths: /api/v1/analytics, /api/v1/reports

---

Overview metrics

GET /api/v1/analytics/overview

Query parameters:

Parameter	Type	Description
agentId	string	Filter to a specific agent
dateFrom	string	ISO 8601 start date
dateTo	string	ISO 8601 end date
groupBy	string	day, week, month
channel	string	Filter by channel

curl "https://api.voisnap.ai/api/v1/analytics/overview?dateFrom=2025-06-01&dateTo=2025-06-30&groupBy=week" \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "period": { "from": "2025-06-01", "to": "2025-06-30" },
  "groupBy": "week",
  "totals": {
    "conversations": 5842,
    "totalDurationSeconds": 1248400,
    "avgDurationSeconds": 214,
    "totalCostUsd": 502.18,
    "avgCostUsdPerConversation": 0.086,
    "transferRate": 0.163,
    "abandonmentRate": 0.092,
    "resolutionRate": 0.745
  },
  "series": [
    {
      "period": "2025-06-01",
      "conversations": 1248,
      "totalDurationSeconds": 267360,
      "avgDurationSeconds": 214,
      "totalCostUsd": 107.33,
      "transferRate": 0.158,
      "resolutionRate": 0.762
    },
    {
      "period": "2025-06-08",
      "conversations": 1592,
      "totalDurationSeconds": 340864,
      "avgDurationSeconds": 214,
      "totalCostUsd": 137.28,
      "transferRate": 0.171,
      "resolutionRate": 0.741
    }
  ]
}

---

Conversation metrics

GET /api/v1/analytics/conversations

curl "https://api.voisnap.ai/api/v1/analytics/conversations?agentId=agt_01HXK8Z3MNPQRS&dateFrom=2025-06-01&dateTo=2025-06-30" \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "period": { "from": "2025-06-01", "to": "2025-06-30" },
  "total": 1482,
  "byStatus": {
    "completed": 1330,
    "failed": 14,
    "abandoned": 138
  },
  "byChannel": {
    "phone": 1240,
    "webrtc": 180,
    "webchat": 62
  },
  "byOutcome": {
    "resolved": 1089,
    "escalated": 241,
    "callback_scheduled": 64,
    "unresolved": 88
  },
  "durationPercentiles": {
    "p50": 187,
    "p75": 284,
    "p90": 412,
    "p99": 598
  },
  "avgSentimentScore": 0.72
}

---

Cost analytics

GET /api/v1/analytics/costs

Query parameters: agentId, dateFrom, dateTo, groupBy

curl "https://api.voisnap.ai/api/v1/analytics/costs?dateFrom=2025-06-01&dateTo=2025-06-30&groupBy=day" \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "period": { "from": "2025-06-01", "to": "2025-06-30" },
  "totalUsd": 502.18,
  "breakdown": {
    "llm": 218.94,
    "tts": 163.21,
    "stt": 89.42,
    "telephony": 30.61
  },
  "byAgent": [
    {
      "agentId": "agt_01HXK8Z3MNPQRS",
      "agentName": "Aria – Support Agent",
      "totalUsd": 127.43,
      "conversations": 1482
    }
  ],
  "series": [
    { "period": "2025-06-01", "totalUsd": 16.74, "conversations": 198 },
    { "period": "2025-06-02", "totalUsd": 14.22, "conversations": 167 }
  ]
}

---

Sentiment trends

GET /api/v1/analytics/sentiment

curl "https://api.voisnap.ai/api/v1/analytics/sentiment?dateFrom=2025-06-01&dateTo=2025-06-30&groupBy=week" \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "period": { "from": "2025-06-01", "to": "2025-06-30" },
  "avgScore": 0.72,
  "distribution": {
    "positive": 0.62,
    "neutral": 0.25,
    "negative": 0.13
  },
  "series": [
    { "period": "2025-06-01", "avgScore": 0.74, "positive": 0.64, "neutral": 0.24, "negative": 0.12 },
    { "period": "2025-06-08", "avgScore": 0.71, "positive": 0.61, "neutral": 0.26, "negative": 0.13 }
  ]
}

---

Top intents

GET /api/v1/analytics/intents

Query parameters: agentId, dateFrom, dateTo, limit

Response:

{
  "period": { "from": "2025-06-01", "to": "2025-06-30" },
  "intents": [
    { "intent": "billing_inquiry", "count": 482, "percentage": 0.325 },
    { "intent": "account_support", "count": 298, "percentage": 0.201 },
    { "intent": "product_question", "count": 241, "percentage": 0.163 },
    { "intent": "cancellation_request", "count": 87, "percentage": 0.059 },
    { "intent": "other", "count": 374, "percentage": 0.252 }
  ]
}

---

Generate a report

POST /api/v1/reports

curl -X POST https://api.voisnap.ai/api/v1/reports \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "conversation_summary",
    "dateFrom": "2025-06-01",
    "dateTo": "2025-06-30",
    "agentIds": ["agt_01HXK8Z3MNPQRS"],
    "format": "csv",
    "includeFields": ["conversationId", "channel", "duration", "outcome", "cost", "sentiment"]
  }'

Response:

{
  "reportId": "rpt_01HXMN8ZABC",
  "status": "generating",
  "estimatedSeconds": 12
}

---

Download a report

GET /api/v1/reports/{reportId}/download

Returns a redirect to a pre-signed download URL. Supports csv and pdf formats.

curl -L "https://api.voisnap.ai/api/v1/reports/rpt_01HXMN8ZABC/download" \
  -H "Authorization: Bearer vsnp_live_..." \
  -o june-report.csv

report_url = client.reports.download_url(report_id="rpt_01HXMN8ZABC")
import urllib.request
urllib.request.urlretrieve(report_url, "june-report.csv")

Reports are available for download for 7 days after generation.