Analytics

The Analytics endpoints provide insights into your support operations. Access dashboard-level metrics, per-agent performance, SLA compliance, ticket volume trends, and heatmaps. All endpoints support flexible date range filtering.

Date Range Parameters

All analytics endpoints accept the following query parameters for date filtering:

Parameter	Type	Description
`period`	string	Preset period (see below). Default: `last_30_days`
`start_date`	date	Custom start date (ISO 8601: `2025-01-01`). Overrides `period`
`end_date`	date	Custom end date (ISO 8601: `2025-01-31`). Overrides `period`

Period Presets

Value	Description
`today`	Current day
`yesterday`	Previous day
`last_7_days`	Last 7 days
`last_30_days`	Last 30 days (default)
`last_90_days`	Last 90 days
`this_month`	Current calendar month
`last_month`	Previous calendar month
`this_quarter`	Current quarter
`this_year`	Current calendar year

Hint: When both period and start_date/end_date are provided, the custom dates take precedence.

Dashboard Metrics

GET /api/v1/analytics/dashboard

Returns a comprehensive overview of your support operations for the selected date range.

Example Request

GET /api/v1/analytics/dashboard?period=last_30_days

Example Response

{
  "data": {
    "period": {
      "start": "2024-12-16",
      "end": "2025-01-15"
    },
    "summary": {
      "total_tickets": 1247,
      "open_tickets": 83,
      "in_progress_tickets": 42,
      "waiting_on_customer": 19,
      "resolved_tickets": 1089,
      "closed_tickets": 14,
      "avg_first_response_time_minutes": 18.4,
      "avg_resolution_time_hours": 4.7,
      "first_contact_resolution_rate": 0.68,
      "customer_satisfaction_score": 4.3
    },
    "tickets_by_status": {
      "new": 12,
      "open": 83,
      "in_progress": 42,
      "waiting_on_customer": 19,
      "escalated": 5,
      "resolved": 1089,
      "closed": 14,
      "auto_resolved": 83
    },
    "tickets_by_priority": {
      "low": 312,
      "medium": 645,
      "high": 231,
      "urgent": 59
    },
    "tickets_by_channel": {
      "email": 523,
      "api": 312,
      "chat": 287,
      "portal": 125
    },
    "tickets_by_department": [
      {
        "department_id": "01912345-1111-7abc-def0-123456789abc",
        "name": "Technical Support",
        "count": 487
      },
      {
        "department_id": "01912345-2222-7abc-def0-123456789abc",
        "name": "Billing",
        "count": 312
      },
      {
        "department_id": "01912345-3333-7abc-def0-123456789abc",
        "name": "Sales",
        "count": 198
      }
    ],
    "comparison": {
      "total_tickets_change": 12.3,
      "avg_response_time_change": -8.5,
      "avg_resolution_time_change": -15.2,
      "satisfaction_change": 0.2
    }
  }
}

The comparison object shows percentage change compared to the previous period of equal length. Negative values indicate improvement for time-based metrics.

Agent Performance

GET /api/v1/analytics/agents

Returns per-agent performance metrics including ticket counts, response times, and customer satisfaction.

Query Parameters

Parameter	Type	Description
`period` / `start_date` / `end_date`	—	Date range (see above)
`department_id`	uuid	Filter by department
`sort_by`	string	Sort field: `tickets_resolved`, `avg_response_time`, `csat_score`. Default: `tickets_resolved`
`sort`	string	`asc` or `desc`. Default: `desc`

Example Response

{
  "data": [
    {
      "agent_id": "01912345-3333-7abc-def0-123456789abc",
      "name": "Alex Johnson",
      "email": "alex@company.com",
      "department": "Technical Support",
      "metrics": {
        "tickets_assigned": 145,
        "tickets_resolved": 132,
        "tickets_escalated": 3,
        "avg_first_response_time_minutes": 12.3,
        "avg_resolution_time_hours": 3.2,
        "first_contact_resolution_rate": 0.74,
        "replies_sent": 487
      },
      "csat": {
        "score": 4.6,
        "total_ratings": 98,
        "distribution": {
          "1": 1,
          "2": 2,
          "3": 5,
          "4": 22,
          "5": 68
        }
      }
    },
    {
      "agent_id": "01912345-4444-7abc-def0-123456789abc",
      "name": "Sarah Chen",
      "email": "sarah@company.com",
      "department": "Billing",
      "metrics": {
        "tickets_assigned": 118,
        "tickets_resolved": 110,
        "tickets_escalated": 1,
        "avg_first_response_time_minutes": 15.7,
        "avg_resolution_time_hours": 2.8,
        "first_contact_resolution_rate": 0.81,
        "replies_sent": 342
      },
      "csat": {
        "score": 4.8,
        "total_ratings": 76,
        "distribution": {
          "1": 0,
          "2": 1,
          "3": 3,
          "4": 14,
          "5": 58
        }
      }
    }
  ]
}

SLA Compliance

GET /api/v1/analytics/sla

Returns SLA compliance metrics across all active SLA policies.

Example Response

{
  "data": {
    "overall_compliance_rate": 0.94,
    "total_tickets_with_sla": 1103,
    "breaches": {
      "total": 66,
      "by_type": {
        "first_response": 23,
        "resolution": 43
      }
    },
    "policies": [
      {
        "policy_id": "01912345-5555-7abc-def0-123456789abc",
        "name": "Critical Priority SLA",
        "compliance_rate": 0.89,
        "tickets_tracked": 59,
        "breaches": 7,
        "avg_first_response_minutes": 8.2,
        "avg_resolution_hours": 2.1,
        "target_first_response_minutes": 15,
        "target_resolution_hours": 4
      },
      {
        "policy_id": "01912345-6666-7abc-def0-123456789abc",
        "name": "Standard SLA",
        "compliance_rate": 0.96,
        "tickets_tracked": 1044,
        "breaches": 42,
        "avg_first_response_minutes": 19.5,
        "avg_resolution_hours": 5.3,
        "target_first_response_minutes": 60,
        "target_resolution_hours": 24
      }
    ]
  }
}

Ticket Volume Trends

GET /api/v1/analytics/trends/ticket-volume

Returns ticket volume data points over time, suitable for charting.

Query Parameters

Parameter	Type	Description
`period` / `start_date` / `end_date`	—	Date range (see above)
`granularity`	string	Data point interval: `hour`, `day`, `week`, `month`. Default: `day`

Example Response

{
  "data": {
    "granularity": "day",
    "points": [
      {
        "date": "2025-01-13",
        "created": 45,
        "resolved": 38,
        "escalated": 2
      },
      {
        "date": "2025-01-14",
        "created": 52,
        "resolved": 47,
        "escalated": 1
      },
      {
        "date": "2025-01-15",
        "created": 39,
        "resolved": 41,
        "escalated": 3
      }
    ]
  }
}

Ticket Heatmap

GET /api/v1/analytics/trends/heatmap

Returns a heatmap of ticket creation volume by day of week and hour of day. Useful for identifying peak support hours and planning staffing.

Example Response

{
  "data": {
    "timezone": "UTC",
    "heatmap": [
      { "day": 0, "hour": 9, "count": 87 },
      { "day": 0, "hour": 10, "count": 112 },
      { "day": 0, "hour": 11, "count": 95 },
      { "day": 0, "hour": 14, "count": 103 },
      { "day": 1, "hour": 9, "count": 91 },
      { "day": 1, "hour": 10, "count": 108 },
      { "day": 1, "hour": 11, "count": 99 },
      { "day": 4, "hour": 15, "count": 78 },
      { "day": 4, "hour": 16, "count": 65 }
    ]
  }
}

The day field uses ISO day numbering: 0 = Monday, 6 = Sunday. The hour field is 0-23 in the tenant's configured timezone. Each entry represents the total ticket count for that day-hour combination in the selected date range.

Export Dashboard Data

GET /api/v1/analytics/export/dashboard

Exports dashboard metrics as a CSV file. Accepts the same date range parameters as the dashboard endpoint.

Response

Returns a CSV file download with Content-Type: text/csv and Content-Disposition: attachment; filename="dashboard-export-2025-01-15.csv".

The CSV includes:

Summary metrics (one row with all key values)
Tickets by status breakdown
Tickets by priority breakdown
Tickets by channel breakdown
Tickets by department breakdown

Export Agent Data

GET /api/v1/analytics/export/agents

Exports agent performance data as a CSV file.

Response

Returns a CSV file with one row per agent, including columns:

agent_name,email,department,tickets_assigned,tickets_resolved,tickets_escalated,avg_first_response_minutes,avg_resolution_hours,first_contact_resolution_rate,csat_score,total_ratings
Alex Johnson,alex@company.com,Technical Support,145,132,3,12.3,3.2,0.74,4.6,98
Sarah Chen,sarah@company.com,Billing,118,110,1,15.7,2.8,0.81,4.8,76

Permissions

Analytics endpoints require the admin or lead role. Regular agents do not have access.

Role	Access
`admin`	All analytics endpoints
`lead`	All analytics endpoints (scoped to their departments)
`agent`	No access (returns `403 FORBIDDEN`)

Best Practices

Use period presets for dashboards — Presets like last_30_days are optimized for caching. Custom date ranges bypass the cache and may be slower on large datasets.
Choose appropriate granularity — Use hour for short periods (today, yesterday), day for weeks/months, week for quarters, and month for yearly views.
Cache export results client-side — CSV exports can be resource-intensive. Cache the downloaded file and offer a "refresh" button rather than fetching on every page load.
Monitor comparison metrics — The comparison object in the dashboard response shows period-over-period changes. Use these to build trend indicators (up/down arrows) in your UI.