AurionAI Docs

Analytics & Reporting

Access conversation analytics, SLA compliance, CSAT trends, and AI insights via the Aurion API.

⚠️ Preview — not yet in the public API

The endpoints on this page are part of the AurionAI helpdesk and are currently accessible only through an authenticated dashboard session. They are not yet exposed through public API keys — a request authenticated with X-API-Key returns 403. Public API-key access is planned. The reference below documents the intended contract.

Analytics & Reporting

The Analytics API provides aggregated metrics and insights across your support operations — conversation volumes, SLA compliance, CSAT scores, and AI-generated insights.

These endpoints are served by the dashboard's RBAC-gated analytics routers, not the public API-key surface. Today they are reachable only with a dashboard session whose role is one of super_admin, tenant_owner, tenant_admin, agent, supervisor, tenant_user, or tenant_readonly. Export creation and listing are restricted further (admin roles only — see Export Analytics). The X-API-Key: itsm_sk_live_… examples below document the intended future public contract.

Plan requirement: Professional plan or higher.

Date range parameters differ by version. The v2 conversation analytics endpoints take date_from / date_to as ISO 8601 datetimes. The v1 voice call endpoints take start_date / end_date as YYYY-MM-DD dates.

Conversation Overview

GET /api/v2/analytics/conversations/overview

Get a high-level view of conversation metrics:

cURL
curl "https://apps.aurionai.net/api/v2/analytics/conversations/overview?date_from=2026-03-01T00:00:00Z&date_to=2026-03-08T23:59:59Z" \
  -H "X-API-Key: itsm_sk_live_xxxx"
Python
import requests

response = requests.get(
    "https://apps.aurionai.net/api/v2/analytics/conversations/overview",
    headers={"X-API-Key": "itsm_sk_live_xxxx"},
    params={"date_from": "2026-03-01T00:00:00Z", "date_to": "2026-03-08T23:59:59Z"},
)
analytics = response.json()
TypeScript
const response = await fetch(
  "https://apps.aurionai.net/api/v2/analytics/conversations/overview?date_from=2026-03-01T00:00:00Z&date_to=2026-03-08T23:59:59Z",
  {
    headers: { "X-API-Key": "itsm_sk_live_xxxx" },
  }
);
const analytics = await response.json();

Response:

{
  "total_conversations": 285,
  "ai_resolved_count": 118,
  "ai_resolution_rate": 41.4,
  "human_resolved_count": 92,
  "escalation_rate": 12.6,
  "first_response_minutes_avg": 12.5,
  "resolution_minutes_median": 252.0,
  "channel_distribution": [
    {"channel": "email", "conversation_count": 145},
    {"channel": "chat", "conversation_count": 80},
    {"channel": "voice", "conversation_count": 35},
    {"channel": "whatsapp", "conversation_count": 25}
  ]
}

SLA Compliance

GET /api/v2/analytics/conversations/sla-compliance

curl "https://apps.aurionai.net/api/v2/analytics/conversations/sla-compliance?date_from=2026-03-01T00:00:00Z&date_to=2026-03-08T23:59:59Z" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

Each SLA bucket reports tracked (conversations with an SLA target), met, breached, and a compliance_rate percentage. by_priority and by_team are lists of buckets, not keyed maps.

{
  "first_response": {"tracked": 285, "met": 275, "breached": 10, "compliance_rate": 96.5},
  "resolution": {"tracked": 285, "met": 262, "breached": 23, "compliance_rate": 91.8},
  "by_priority": [
    {"priority": "urgent", "tracked": 25, "met": 22, "breached": 3, "compliance_rate": 88.0},
    {"priority": "high", "tracked": 50, "met": 46, "breached": 4, "compliance_rate": 92.0},
    {"priority": "medium", "tracked": 150, "met": 144, "breached": 6, "compliance_rate": 96.0},
    {"priority": "low", "tracked": 60, "met": 59, "breached": 1, "compliance_rate": 98.0}
  ],
  "by_team": [
    {"team_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef", "team_name": "Tier 1", "tracked": 180, "met": 171, "breached": 9, "compliance_rate": 95.0}
  ]
}

CSAT Analytics

GET /api/v2/analytics/conversations/csat

Returns CSAT aggregates, a 30-day trend, and a per-agent breakdown. Optional agent_id and team_id filters (both UUIDs) scope the metrics to conversations assigned to that agent or team.

curl "https://apps.aurionai.net/api/v2/analytics/conversations/csat?date_from=2026-03-01T00:00:00Z&date_to=2026-03-08T23:59:59Z" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "total_responses": 120,
  "rated_responses": 112,
  "avg_rating": 4.3,
  "positive_responses": 96,
  "positive_rate": 85.7,
  "distribution": [
    {"rating": 5, "response_count": 64},
    {"rating": 4, "response_count": 32},
    {"rating": 3, "response_count": 10},
    {"rating": 2, "response_count": 4},
    {"rating": 1, "response_count": 2}
  ],
  "trend": [
    {"day": "2026-03-01", "count": 14, "avg_rating": 4.4}
  ],
  "per_agent": [
    {"assignee_user_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "assignee_name": "Jane Doe", "response_count": 40, "avg_rating": 4.5, "positive_rate": 90.0}
  ]
}

CSAT Responses (drilldown)

GET /api/v2/analytics/conversations/csat/responses

Lists individual CSAT responses joined with conversation and agent context. Supports date_from / date_to, optional agent_id / team_id (UUID) filters, and offset pagination via limit (1–200, default 50) and offset (default 0). The envelope is named items.

curl "https://apps.aurionai.net/api/v2/analytics/conversations/csat/responses?date_from=2026-03-01T00:00:00Z&date_to=2026-03-08T23:59:59Z&limit=50&offset=0" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "items": [
    {
      "id": "c0ffee00-1234-5678-9abc-def012345678",
      "conversation_id": "11112222-3333-4444-5555-666677778888",
      "contact_id": "99990000-aaaa-bbbb-cccc-ddddeeeeffff",
      "rating": 5,
      "comment": "Resolved quickly, thanks!",
      "followup_answer": null,
      "channel": "email",
      "sent_at": "2026-03-02T09:15:00Z",
      "responded_at": "2026-03-02T10:02:00Z",
      "conversation_subject": "VPN cannot connect",
      "assignee_user_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "assignee_name": "Jane Doe",
      "assignee_team_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "assignee_team_name": "Tier 1"
    }
  ],
  "total": 112,
  "limit": 50,
  "offset": 0
}

Resolution Rates (CS)

GET /api/v2/analytics/conversations/resolution-rates

CS-side AI-vs-human resolution split and a resolution-by-priority breakdown. Supports date_from / date_to and an optional team_id (UUID) filter.

curl "https://apps.aurionai.net/api/v2/analytics/conversations/resolution-rates?date_from=2026-03-01T00:00:00Z&date_to=2026-03-08T23:59:59Z" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "total_conversations": 285,
  "resolved_count": 210,
  "ai_resolved_count": 118,
  "human_resolved_count": 92,
  "ai_resolution_rate": 41.4,
  "human_resolution_rate": 32.3,
  "resolution_rate": 73.7,
  "by_priority": [
    {"priority": "high", "total": 50, "resolved": 46, "ai_resolved": 20, "human_resolved": 26, "resolution_rate": 92.0}
  ]
}

Teams (filter dropdown)

GET /api/v2/analytics/conversations/teams

Lists the teams available as a filter on the Resolution Rates and CSAT views. Takes no query parameters.

curl "https://apps.aurionai.net/api/v2/analytics/conversations/teams" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "teams": [
    {"team_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef", "team_name": "Tier 1"}
  ]
}

AI Insights

GET /api/v2/analytics/conversations/insights

Get AI-generated insights from conversation patterns:

curl "https://apps.aurionai.net/api/v2/analytics/conversations/insights?date_from=2026-03-01T00:00:00Z&date_to=2026-03-08T23:59:59Z" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

The insights response is a structured object covering CSAT, busiest hours, top topics, agent/team performance, Help Center deflection, the SLA-breach trend, email-channel metrics, and aggregation health, plus a top-level metadata echo of the requested date range.

{
  "csat": {
    "total_responses": 120,
    "rated_responses": 112,
    "avg_rating": 4.3,
    "positive_responses": 96,
    "positive_rate": 85.7,
    "distribution": [{"rating": 5, "response_count": 64}],
    "trend": [{"day": "2026-03-01", "count": 14, "avg_rating": 4.4}],
    "per_agent": [{"assignee_user_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "assignee_name": "Jane Doe", "response_count": 40, "avg_rating": 4.5, "positive_rate": 90.0}]
  },
  "busiest_hours": [
    {"hour_utc": 14, "conversation_count": 38}
  ],
  "top_topics": [
    {"topic": "VPN connectivity", "conversation_count": 42, "share": 14.7}
  ],
  "agent_performance": [
    {"assignee_user_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "assignee_name": "Jane Doe", "assigned_count": 60, "resolved_count": 55, "resolution_rate": 91.7, "avg_first_response_minutes": 9.2, "avg_resolution_minutes": 210.0}
  ],
  "team_performance": [
    {"team_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef", "team_name": "Tier 1", "assigned_count": 180, "resolved_count": 171, "resolution_rate": 95.0, "avg_resolution_minutes": 198.0}
  ],
  "help_center_deflection": {
    "article_count": 120,
    "total_views": 5400,
    "helpful_feedback": 410,
    "not_helpful_feedback": 60,
    "deflection_rate": 22.5,
    "top_articles": [
      {"article_id": "kb_001", "title": "Reset your VPN client", "slug": "reset-vpn-client", "view_count": 320, "helpful_count": 41, "not_helpful_count": 3}
    ]
  },
  "sla_breach_trend": [
    {"day": "2026-03-01", "tracked": 40, "breached": 3, "met": 37, "compliance_rate": 92.5}
  ],
  "email_channel_metrics": {
    "total_channels": 3,
    "active_channels": 2,
    "email_conversations": 145,
    "inbound_messages": 320,
    "outbound_messages": 298,
    "bounced_contacts": 4,
    "complained_contacts": 1,
    "by_channel": [
      {"channel_id": "ch_001", "address": "support@acme.example", "status": "active", "conversation_count": 130}
    ]
  },
  "aggregation_health": {
    "target_conversation_volume": 100000,
    "per_query_budget_ms": 500.0,
    "total_budget_ms": 2000.0,
    "total_runtime_ms": 480.0,
    "target_met": true,
    "overview_ms": 120.0,
    "sla_compliance_ms": 160.0,
    "agent_performance_ms": 200.0
  },
  "metadata": {
    "date_from": "2026-03-01T00:00:00+00:00",
    "date_to": "2026-03-08T23:59:59+00:00"
  }
}

Unified Overview

GET /api/v2/analytics/unified-overview

Cross-product analytics combining voice agent, CS helpdesk, and knowledge base metrics. The profile field reflects the tenant's product profile (voice, platform, or complete); the voice, cs, cross_product, and kb blocks are present only for the products the tenant has enabled (otherwise null).

curl "https://apps.aurionai.net/api/v2/analytics/unified-overview?date_from=2026-03-01T00:00:00Z&date_to=2026-03-08T23:59:59Z" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "profile": "complete",
  "voice": {
    "total_calls": 156,
    "completed_calls": 130,
    "failed_calls": 26,
    "avg_duration_seconds": 245.0,
    "first_call_resolution_rate": 62.8,
    "tickets_created": 98,
    "escalation_count": 32
  },
  "cs": {
    "total_conversations": 285,
    "ai_resolved_count": 118,
    "ai_resolution_rate": 41.4,
    "human_resolved_count": 92,
    "escalation_rate": 12.6,
    "first_response_minutes_avg": 12.5,
    "resolution_minutes_median": 252.0,
    "csat_avg": 4.3,
    "channel_distribution": [
      {"channel": "email", "conversation_count": 145}
    ]
  },
  "cross_product": {
    "total_interactions": 441,
    "blended_resolution_rate": 70.5,
    "voice_share": 35.4,
    "cs_share": 64.6
  },
  "kb": {
    "total_published": 120,
    "total_views": 5400,
    "helpfulness_rate": 87.2,
    "ai_resolutions": 64
  }
}

Aggregation Health

GET /api/v2/analytics/conversations/aggregation-health

Check the data pipeline health to ensure analytics data is up to date. Accepts optional date_from / date_to.

curl "https://apps.aurionai.net/api/v2/analytics/conversations/aggregation-health?date_from=2026-03-01T00:00:00Z&date_to=2026-03-08T23:59:59Z" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "target_conversation_volume": 100000,
  "per_query_budget_ms": 500.0,
  "total_budget_ms": 2000.0,
  "total_runtime_ms": 480.0,
  "target_met": true,
  "overview_ms": 120.0,
  "sla_compliance_ms": 160.0,
  "agent_performance_ms": 200.0
}

Query Parameters (v2)

All v2 conversation analytics endpoints accept:

ParameterTypeDescription
date_fromstringLower bound of the range (ISO 8601 datetime)
date_tostringUpper bound of the range (ISO 8601 datetime)
team_idstringFilter by assignee team UUID (resolution-rates, csat, csat/responses)
agent_idstringFilter by assignee agent UUID (csat, csat/responses)
limitintegerPage size for csat/responses (1–200, default 50)
offsetintegerPage offset for csat/responses (default 0)

Voice Call Analytics (v1)

The v1 analytics endpoints provide metrics specific to voice call operations. They take start_date / end_date as YYYY-MM-DD dates and an optional tz (IANA timezone, e.g. Europe/Paris) that controls how days are bucketed.

Call Metrics

GET /api/v1/analytics/call-metrics

Returns KPIs, a daily call-volume trend, an outcome breakdown, and a peak-hours heatmap. Optional outcome filters to a single call outcome.

curl "https://apps.aurionai.net/api/v1/analytics/call-metrics?start_date=2026-03-01&end_date=2026-03-08" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query parameters: start_date (required), end_date (required), outcome (optional), tz (optional IANA timezone).

Response:

{
  "kpis": {
    "total_calls": 156,
    "completed_calls": 130,
    "failed_calls": 26,
    "avg_duration_seconds": 245.0,
    "first_call_resolution_rate": 62.8,
    "tickets_created": 98,
    "escalation_count": 32,
    "period_start": "2026-03-01",
    "period_end": "2026-03-08"
  },
  "call_volume": [
    {"date": "2026-03-01", "total_calls": 22, "completed_calls": 18, "failed_calls": 4}
  ],
  "outcome_breakdown": [
    {"outcome": "ticket_created", "count": 98, "percentage": 62.8},
    {"outcome": "escalated", "count": 32, "percentage": 20.5},
    {"outcome": "abandoned", "count": 26, "percentage": 16.7}
  ],
  "peak_hours": [
    {"hour": 14, "day_of_week": 2, "call_count": 12}
  ]
}

Resolution Rates

GET /api/v1/analytics/resolution-rates

curl "https://apps.aurionai.net/api/v1/analytics/resolution-rates?start_date=2026-03-01&end_date=2026-03-08" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "fcr_trend": [],
  "resolution_by_category": [],
  "avg_resolution_time_seconds": 252.0,
  "period_comparison": null
}

Usage Patterns

GET /api/v1/analytics/usage-patterns

curl "https://apps.aurionai.net/api/v1/analytics/usage-patterns?start_date=2026-03-01&end_date=2026-03-08" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "hourly_distribution": [],
  "weekly_distribution": [],
  "monthly_trends": [],
  "llm_usage": [
    {"provider": "groq", "total_requests": 1240, "total_input_tokens": 410000, "total_output_tokens": 96000, "avg_latency_ms": 320.0, "error_count": 3}
  ],
  "avg_tokens_per_call": 412.0
}

GET /api/v1/analytics/search

Search call records by phone number. Rate-limited to 10 searches per minute per user (enforced via Redis). All searches are audit-logged and the phone number is redacted in the response for PII protection.

Query parameters: phone (required, minimum 4 chars), start_date (required), end_date (required), limit (optional, 1–100, default 50), tz (optional IANA timezone).

curl "https://apps.aurionai.net/api/v1/analytics/search?phone=%2B33612345678&start_date=2026-03-01&end_date=2026-03-08" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "results": [
    {
      "call_id": "11112222-3333-4444-5555-666677778888",
      "phone_number_redacted": "***-***-5678",
      "start_time": "2026-03-02T09:15:00Z",
      "duration_seconds": 245,
      "outcome": "ticket_created",
      "status": "completed"
    }
  ],
  "total_count": 1,
  "search_term_redacted": "***-***-5678"
}

Export Analytics (v1)

POST /api/v1/analytics/export

Create an export of analytics data. Admin roles only (super_admin, tenant_admin). All exports apply server-side PII redaction, and the request is logged to the audit log.

Request body:

FieldTypeRequiredDescription
formatstringyesOne of csv, json, pdf
start_datestringyesYYYY-MM-DD
end_datestringyesYYYY-MM-DD
scopestringnoOne of voice (default), conversations, all, sla_quality, resolution_rates, performance
include_call_detailsbooleannoDefault true
include_transcriptsbooleannoDefault false
include_conversationsbooleannoDefault false
tzstringnoIANA timezone (e.g. Europe/Paris)
curl -X POST "https://apps.aurionai.net/api/v1/analytics/export" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "start_date": "2026-03-01",
    "end_date": "2026-03-08",
    "scope": "voice",
    "include_call_details": true,
    "include_transcripts": false
  }'

Response:

{
  "export_id": "c0ffee00-1234-5678-9abc-def012345678",
  "download_url": "/api/v1/analytics/export/c0ffee00-1234-5678-9abc-def012345678/download?format=csv&start_date=2026-03-01&end_date=2026-03-08",
  "expires_at": "2026-03-09T12:00:00Z"
}

List recent exports (last 24 hours):

GET /api/v1/analytics/exports — admin roles only (super_admin, tenant_admin).

curl "https://apps.aurionai.net/api/v1/analytics/exports" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "exports": [
    {
      "export_id": "c0ffee00-1234-5678-9abc-def012345678",
      "format": "csv",
      "scope": "voice",
      "start_date": "2026-03-01",
      "end_date": "2026-03-08",
      "include_call_details": true,
      "include_transcripts": false,
      "include_conversations": false,
      "download_url": "/api/v1/analytics/export/c0ffee00-1234-5678-9abc-def012345678/download?format=csv&start_date=2026-03-01&end_date=2026-03-08",
      "created_at": "2026-03-08T12:00:00Z",
      "expires_at": "2026-03-09T12:00:00Z"
    }
  ]
}

Download a completed export:

GET /api/v1/analytics/export/{export_id}/download

curl "https://apps.aurionai.net/api/v1/analytics/export/{export_id}/download" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -o export.csv

Access Control

There is no analytics API-key scope — /api/v1/analytics and /api/v2/analytics are not part of the API-key allowlist, so a request authenticated with X-API-Key returns 403 today (see the preview banner at the top of this page). These endpoints are gated by dashboard RBAC roles:

EndpointsRequired role
All read (GET) analytics endpoints (v1 + v2)super_admin, tenant_owner, tenant_admin, agent, supervisor, tenant_user, or tenant_readonly
POST /api/v1/analytics/export, GET /api/v1/analytics/exportssuper_admin or tenant_admin only

Errors

Error responses follow the FastAPI standard JSON shape { "detail": "<message>" } for all 4xx/5xx. When the per-API-key rate limit is exceeded, 429 Too Many Requests returns { "detail": "API key rate limit exceeded", "limit": 300 } with a Retry-After header. Branch on the HTTP status and the detail string.

Rate limits

A default of 300 requests per minute per API key applies in both production and staging. When the limit is exceeded, the 429 response carries Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining headers. (Once these endpoints are exposed to public API keys, this limit will apply on top of the dashboard RBAC gating.)

CSAT Surveys

Configure and manage customer satisfaction surveys via the Aurion API.

Knowledge Base

Create and manage knowledge base articles programmatically via the Aurion API.

On this page

Analytics & ReportingConversation OverviewSLA ComplianceCSAT AnalyticsCSAT Responses (drilldown)Resolution Rates (CS)Teams (filter dropdown)AI InsightsUnified OverviewAggregation HealthQuery Parameters (v2)Voice Call Analytics (v1)Call MetricsResolution RatesUsage PatternsPhone Number SearchExport Analytics (v1)Related GuidesAccess ControlErrorsRate limits