Analytics & Reporting

Real-time analytics on message volume, response times, escalation rates, and gate failure breakdown.

Analytics Overview

Get high-level metrics for your tenant.

GET /api/tenants/me/analytics/overview

Response

{
  "period": "today",
  "metrics": {
    "totalConversations": 142,
    "totalMessages": 487,
    "avgResponseTime": 2.3,
    "escalationRate": 0.08,
    "gatePassRate": 0.94,
    "activeCustomers": 89
  },
  "trends": {
    "messagesLastHour": 45,
    "escalationsLastHour": 2,
    "responseTimeLastHour": 2.1
  },
  "generatedAt": "2026-03-12T14:30:00Z"
}

Metric Definitions

Metric	Definition
totalConversations	Number of unique conversations started
totalMessages	Total customer + AI messages
avgResponseTime	Average seconds from customer message to AI reply
escalationRate	% of conversations escalated to human
gatePassRate	% of AI replies that passed all 5 gates on first try
activeCustomers	Unique customers who messaged today

---

Gate Performance

Detailed breakdown of gate pass/fail rates.

GET /api/tenants/me/analytics/gates

Response

{
  "period": "today",
  "gates": {
    "repetition": {
      "passRate": 0.98,
      "failCount": 3,
      "avgScore": 0.45
    },
    "hallucination": {
      "passRate": 0.94,
      "failCount": 8,
      "commonClaims": [
        "price 99,000đ",
        "free shipping",
        "delivery in 24h"
      ]
    },
    "tone": {
      "passRate": 0.99,
      "failCount": 1,
      "bannedPhrasesTriggered": ["tôi không biết"]
    },
    "relevance": {
      "passRate": 0.96,
      "failCount": 5,
      "avgScore": 0.72
    },
    "length": {
      "passRate": 0.99,
      "failCount": 2,
      "avgWordCount": 95
    }
  },
  "totalGateChecks": 432
}

Insights

• Hallucination gate failing most? Review your KB entries — AI is making unverified claims
• Repetition failures? Consider reducing response length or pausing rapid-fire messages
• Tone gate failing? Update your prohibitions list or rephrase customer instructions

---

Time Series Data

Metrics over time (last 7 days).

GET /api/tenants/me/analytics/timeseries?metric=avgResponseTime&days=7

Response

{
  "metric": "avgResponseTime",
  "data": [
    { "date": "2026-03-06", "value": 2.1 },
    { "date": "2026-03-07", "value": 2.3 },
    { "date": "2026-03-08", "value": 2.2 },
    { "date": "2026-03-09", "value": 2.4 },
    { "date": "2026-03-10", "value": 2.1 },
    { "date": "2026-03-11", "value": 2.2 },
    { "date": "2026-03-12", "value": 2.3 }
  ]
}

Useful for charting trends in your dashboard.

---

Message Volume by Channel

Breakdown by channel (Pancake, Zalo, etc).

GET /api/tenants/me/analytics/channels

Response

{
  "period": "today",
  "channels": {
    "pancake": {
      "messageCount": 350,
      "conversationCount": 100,
      "escalationRate": 0.07
    },
    "facebook": {
      "messageCount": 137,
      "conversationCount": 42,
      "escalationRate": 0.10
    }
  }
}

---

Message Volume by Hour

See which hours have highest traffic.

GET /api/tenants/me/analytics/volume-by-hour?date=2026-03-12

Response

{
  "date": "2026-03-12",
  "hourly": [
    { "hour": 8, "messages": 23 },
    { "hour": 9, "messages": 58 },
    { "hour": 10, "messages": 87 },
    { "hour": 11, "messages": 102 },
    { "hour": 12, "messages": 89 },
    ...
  ]
}

Use to optimize support hours or alert thresholds.

---

Customer Cohort Analysis

Analyze customer segments.

GET /api/tenants/me/analytics/cohorts

Response

{
  "cohorts": {
    "new_customers": {
      "count": 12,
      "avgFirstResponseTime": 3.2,
      "escalationRate": 0.15
    },
    "returning_customers": {
      "count": 77,
      "avgFirstResponseTime": 2.1,
      "escalationRate": 0.06
    },
    "vip_customers": {
      "count": 5,
      "avgFirstResponseTime": 1.8,
      "escalationRate": 0.02
    }
  }
}

• New customers have longer response times and more escalations (less context)
• VIP customers get faster, more accurate responses (high trust score)

---

Export Analytics

Export analytics to CSV.

GET /api/tenants/me/analytics/export?format=csv&days=30

Response: CSV file with all metrics and trends.

---

Webhook Events

Dolly sends analytics events to ClickHouse for real-time warehouse queries. Events include:

• message.received — Customer message received
• message.processed — AI response generated
• message.delivered — Reply sent to customer
• gate.evaluated — Gate check result
• escalation.created — Conversation escalated
• tool.executed — Tool call executed

Access ClickHouse directly for custom queries (see infrastructure docs).

---

Alerts (Phase 2)

Phase 1 provides metrics. Phase 2 will add:

• Alert when escalation rate > 20%
• Alert when avg response time > 5s
• Alert when gate pass rate < 80%
• Daily digest summary

---

Error Responses

Error	HTTP	Cause
INVALID_REQUEST	400	Invalid date range, metric not found
INTERNAL_ERROR	500	Analytics query failed