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

avg_rating is null when no rated response falls in the window — an unknown average, not a measured 0. The same holds for csat.avg_rating in the insights response.

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

avg_first_response_minutes and avg_resolution_minutes in agent_performance / team_performance are null when the agent or team has no first response (or no resolved conversation) in the window — an unknown average, not a measured 0.

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
}

POST /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.

This endpoint is a POST even though it is a read, and deliberately so: the search term is a customer's phone number, and a query parameter is part of the request line, which load balancers, reverse proxies and APM agents record verbatim into stores with weaker retention and access controls than the audit log. Send the term in the request body — never append it to the URL.

Request body (application/json): phone (required, 4–40 chars), start_date (required), end_date (required), limit (optional, 1–100, default 50), tz (optional IANA timezone).

# Read the key from the environment — never paste it into a shell history, and
# never put the phone number in the URL.
curl -X POST "https://apps.aurionai.net/api/v1/analytics/search" \
  -H "X-API-Key: $AURION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+33612345678", "start_date": "2026-03-01", "end_date": "2026-03-08"}'

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 a rate limit is exceeded, the API returns 429 Too Many Requests; its body and headers depend on which limit was hit (see Error Handling → Rate Limiting). Branch on the HTTP status.

Rate limits

The plan-based limits described in Error Handling → Rate Limiting apply in both production and staging. (Once these endpoints are exposed to public API keys, these limits 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