Skip to main content
The Dashboard API provides analytics and metrics data for visualizing helpdesk performance.

​
Get Dashboard Data

Retrieve dashboard metrics and charts based on filters. 
helpdesk.api.dashboard.get_dashboard_data(
    dashboard_type: str,
    filters: dict = None
)
From helpdesk/api/dashboard.py:25 - Agent-only endpoint for fetching dashboard analytics.

​
Parameters

​
dashboard_type
string
required
Type of dashboard data to retrieve:
  • number_card - Summary metrics (ticket count, SLA %, avg response time, etc.)
  • trend - Time-series data for trends
  • master - Breakdown charts by team, type, priority, channel
​
filters
object
Filter options for the dashboard data:
  • from_date (string) - Start date (defaults to 30 days ago)
  • to_date (string) - End date (defaults to today)
  • team (string) - Filter by specific team
  • agent (string) - Filter by specific agent (use @me for current user)

​
Response

Returns different data structures based on dashboard_type:

​
Number Card Data

Array of metric cards: 
[
  {
    "title": "Tickets",
    "value": 42,
    "delta": 15.5,
    "deltaSuffix": "%",
    "negativeIsBetter": true,
    "tooltip": "Total number of tickets created"
  },
  {
    "title": "% SLA Fulfilled",
    "value": 87.3,
    "suffix": "%",
    "delta": 5.2,
    "deltaSuffix": "%",
    "tooltip": "% of tickets created that were resolved within SLA"
  }
]
​
title
string
Metric name
​
value
number
Current period value
​
delta
number
Change from previous period
​
suffix
string
Unit suffix (e.g., ”%”, ” hrs”, ” days”)
​
negativeIsBetter
boolean
Whether a decrease is positive (true for tickets, response time)

​
Trend Data

Array of time-series charts: 
[
  {
    "type": "axis",
    "title": "Ticket Trend",
    "subtitle": "Average tickets per day is around 12",
    "data": [
      {"date": "2024-01-01", "Open": 5, "Closed": 3, "SLA Fulfilled": 100},
      {"date": "2024-01-02", "Open": 8, "Closed": 6, "SLA Fulfilled": 75}
    ],
    "xAxis": {"key": "date", "type": "time", "timeGrain": "day"},
    "yAxis": {"title": "Tickets"},
    "series": [
      {"name": "Closed", "type": "bar"},
      {"name": "Open", "type": "bar"},
      {"name": "SLA Fulfilled", "type": "line", "axis": "y2"}
    ]
  }
]

​
Master Dashboard Data

Array of breakdown charts (team, type, priority, channel): 
[
  {
    "type": "pie",
    "title": "Tickets by Team",
    "subtitle": "Percentage of Total Tickets by Team",
    "data": [
      {"team": "Support Team", "count": 45},
      {"team": "Technical Team", "count": 32}
    ],
    "categoryColumn": "team",
    "valueColumn": "count"
  }
]

​
Permissions

  • Agent-only: Requires @agent_only decorator
  • Managers: Can view any agent/team data
  • Agents: Can only view their own data (agent filter must be @me or their user ID)

​
Example

import requests

# Get number cards for current user's last 30 days
response = requests.post(
    "https://your-site.frappe.cloud/api/method/helpdesk.api.dashboard.get_dashboard_data",
    headers={"Authorization": f"token {api_key}:{api_secret}"},
    json={
        "dashboard_type": "number_card",
        "filters": {
            "agent": "@me",
            "from_date": "2024-01-01",
            "to_date": "2024-01-31"
        }
    }
)

metrics = response.json()["message"]
for metric in metrics:
    print(f"{metric['title']}: {metric['value']}")

​
Number Card Metrics

The number card dashboard includes these metrics (from helpdesk/api/dashboard.py:140):

​
Tickets

Total tickets created in the period.

​
% SLA Fulfilled

Percentage of resolved tickets that met SLA requirements.

​
Avg. First Response

Average time (in hours) to first respond to a ticket.

​
Avg. Resolution

Average time (in days) to resolve a ticket.

​
Avg. Feedback Rating

Average customer feedback rating (out of 5 stars).

​
Trend Charts

The trend dashboard includes (from helpdesk/api/dashboard.py:239):

​
Ticket Trend

Daily breakdown of open vs closed tickets, with SLA fulfillment rate overlay.

​
Feedback Trend

Daily average feedback rating and number of rated tickets.

​
Master Dashboard Charts

The master dashboard includes (from helpdesk/api/dashboard.py:409):

​
Tickets by Team

Distribution of tickets across agent groups.

​
Tickets by Type

Breakdown by ticket type (if configured).

​
Tickets by Priority

Distribution across priority levels.

​
Tickets by Channel

Split between portal and email ticket creation.

​
Filter Behavior

​
Date Ranges

  • Defaults to last 30 days if not specified
  • to_date is inclusive (uses < to_date + 1 day internally)
  • Previous period for delta calculation has same length as current period

​
Team Filter

Filters by agent_group field on tickets.

​
Agent Filter

Uses JSON_SEARCH to find agent in ticket’s _assign field. The special value @me is replaced with frappe.session.user.

​
Error Handling

Non-managers attempting to view other agents’ data will receive a PermissionError:
"You are not allowed to view this dashboard data."

Tickets API

Query individual tickets

Agents API

Manage agents for team filters

Build docs developers (and LLMs) love

Get started for freeTalk to us