Graph Analytics

Get usage statistics and performance metrics for an assistant graph

GET /api/v1/assistant-graphs/{graph_id}/analytics

cURL

curl "https://api.burki.dev/api/v1/assistant-graphs/1/analytics?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "graph_id": 1,
  "graph_name": "Customer Service Router",
  "period_days": 30,
  "total_sessions": 1250,
  "total_transitions": 2180,
  "avg_session_duration": 245,
  "most_used_transitions": [
    {
      "from_node": "Receptionist",
      "to_node": "Support Agent",
      "count": 890,
      "percentage": 40.8
    },
    {
      "from_node": "Receptionist",
      "to_node": "Sales Specialist",
      "count": 720,
      "percentage": 33.0
    },
    {
      "from_node": "Support Agent",
      "to_node": "Human Escalation",
      "count": 180,
      "percentage": 8.3
    }
  ],
  "node_usage_stats": {
    "101": {
      "node_name": "Receptionist",
      "sessions_started": 1250,
      "avg_time_in_node": 45,
      "exit_rate": 0.0
    },
    "102": {
      "node_name": "Sales Specialist",
      "sessions_started": 720,
      "avg_time_in_node": 180,
      "exit_rate": 0.85
    },
    "103": {
      "node_name": "Support Agent",
      "sessions_started": 890,
      "avg_time_in_node": 150,
      "exit_rate": 0.80
    },
    "104": {
      "node_name": "Human Escalation",
      "sessions_started": 180,
      "avg_time_in_node": 0,
      "exit_rate": 1.0
    }
  }
}

Retrieve analytics data for a specific assistant graph, including usage statistics, transition patterns, and performance metrics over a specified time period.

Path Parameters

graph_id · integer · required

The unique identifier of the graph.

Query Parameters

days · integer · default: "30"

Number of days to analyze. Must be between 1 and 365.

Response

graph_id · integer

The graph ID.

graph_name · string

Name of the graph.

period_days · integer

Number of days analyzed.

total_sessions · integer

Total number of conversation sessions during the period.

total_transitions · integer

Total number of assistant transitions during the period.

avg_session_duration · number

Average session duration in seconds.

most_used_transitions · array

List of most frequently used transition paths.

node_usage_stats · object

Usage statistics broken down by node.

cURL

curl "https://api.burki.dev/api/v1/assistant-graphs/1/analytics?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "graph_id": 1,
  "graph_name": "Customer Service Router",
  "period_days": 30,
  "total_sessions": 1250,
  "total_transitions": 2180,
  "avg_session_duration": 245,
  "most_used_transitions": [
    {
      "from_node": "Receptionist",
      "to_node": "Support Agent",
      "count": 890,
      "percentage": 40.8
    },
    {
      "from_node": "Receptionist",
      "to_node": "Sales Specialist",
      "count": 720,
      "percentage": 33.0
    },
    {
      "from_node": "Support Agent",
      "to_node": "Human Escalation",
      "count": 180,
      "percentage": 8.3
    }
  ],
  "node_usage_stats": {
    "101": {
      "node_name": "Receptionist",
      "sessions_started": 1250,
      "avg_time_in_node": 45,
      "exit_rate": 0.0
    },
    "102": {
      "node_name": "Sales Specialist",
      "sessions_started": 720,
      "avg_time_in_node": 180,
      "exit_rate": 0.85
    },
    "103": {
      "node_name": "Support Agent",
      "sessions_started": 890,
      "avg_time_in_node": 150,
      "exit_rate": 0.80
    },
    "104": {
      "node_name": "Human Escalation",
      "sessions_started": 180,
      "avg_time_in_node": 0,
      "exit_rate": 1.0
    }
  }
}

Understanding the Metrics

Session Metrics

Metric	Description
total_sessions	Number of unique conversations that used this graph
avg_session_duration	Average time from session start to end (seconds)

Transition Metrics

Metric	Description
total_transitions	Total number of times conversations moved between assistants
most_used_transitions	Ranking of most common assistant-to-assistant paths

Node Usage Stats

Metric	Description
sessions_started	Number of sessions where this node was active
avg_time_in_node	Average time spent with this assistant (seconds)
exit_rate	Percentage of sessions that ended at this node

Use Cases for Analytics

Identify Bottlenecks

High avg_time_in_node for a specific assistant may indicate:

• Complex issues that need better tooling
• Knowledge gaps requiring additional training
• Need for more specialized assistants

Optimize Routing

Analyze most_used_transitions to:

• Identify if entry conditions are working as expected
• Find opportunities to streamline common paths
• Validate that intents are being detected correctly

Reduce Escalations

Monitor escalation node usage to:

• Track escalation rates over time
• Identify which paths lead to escalations
• Measure impact of improvements

Capacity Planning

Use session volumes to:

• Plan for peak hours
• Allocate human agent resources
• Justify investment in specialized assistants

Error Responses

Status Code	Description
401	Unauthorized - Invalid or missing API key
404	Graph not found in your organization
500	Server error retrieving analytics

Analytics data is aggregated asynchronously. Recent sessions (within the last few minutes) may not be reflected in the analytics immediately.