How to view agent performance metrics in Zoho Desk

Agent performance metrics in Zoho Desk can be accessed through dedicated API endpoints that surface productivity data, live status monitoring, and skill assignments for every agent in your support organisation.

Why this matters

Support managers need a clear, real-time picture of how their team is performing — from ticket resolution rates to current availability. Whether you are building a custom dashboard, running a periodic review, or integrating Zoho Desk data into a broader BI tool, knowing which endpoints to call and what permissions to configure is essential. This guide (from Beam Help — independent expert support for Zoho, not official Zoho support) walks you through the full process.

---

Step-by-step

Step 1. Confirm your OAuth scopes are in place.

Before any metrics call will succeed, your connected application must be authorised with the correct Zoho Desk OAuth scopes. At minimum you need Desk.basic.READ (covers agents, departments, and organisations) alongside any ticket or settings scopes relevant to your use case. ^[5] Make sure these scopes are present in your OAuth configuration and that the token has been refreshed after any scope changes. ^[5]

Step 2. Retrieve agent performance metrics.

Send a GET request to the endpoint /api/v1/doc/agentperformancemetrics, passing any filter or pagination parameters as a query-parameter dictionary. ^[1] This operation — identified internally as getagentperformancemetrics — returns productivity-focused data for your agents. ^[1] A minimal Python call looks like this:

result = client.get_agent_performance_metrics(p={"department": "Support"})

Replace the parameter dictionary with whatever filters your reporting window requires. ^[1]

Step 3. Pull live agent status data.

For real-time availability and workload information, call GET /api/v1/doc/agentstatusmonitoring using the getagentstatusmonitoring operation. ^[2] This endpoint is designed specifically for ongoing status observation — useful for wallboards or live supervisor views. ^[2] Pass the same optional parameter dictionary p to scope results by department or team if needed. ^[2]

Step 4. Retrieve agent skill mappings (optional but recommended).

If your Desk setup uses skill-based routing, you will also want to query GET /api/v1/doc/agentskillmapping via the getagentskillmapping operation. ^[4] This lets you cross-reference performance data with each agent's assigned skill set, giving context to resolution times and ticket volumes. ^[4]

Step 5. Format and present the returned data.

Once you receive tool results, surface the key data fields in a readable format for stakeholders. A recommended pattern is to display each field on its own line (Name, Status, Owner/Agent, etc.), skipping empty values and internal IDs. ^[3] Avoid dumping raw JSON directly into reports — parse and label each field explicitly. ^[3]

Step 6. Automate with a scheduled job (optional).

For recurring performance reviews, wrap the calls from Steps 2–4 in a scheduled script. Store the responses in your data warehouse or BI layer, keyed by timestamp and agent ID, so you can track trends over time. Because the endpoints accept a parameter dictionary, you can vary the date range or department filter on each run without changing the core logic. ^[1][2]

---

Common pitfalls

• Missing Desk.basic.READ scope. This is the most frequent cause of 401/403 errors when querying agent endpoints. Even if your token has broad ticket permissions, agent and department data sits under the basic scope family. Double-check your scope list before debugging the endpoint itself. ^[5]
• Stale access tokens. Zoho OAuth tokens expire (typically after 3600 seconds). If your integration does not automatically refresh the token, calls to all three endpoints will fail silently or return authentication errors. Implement a refresh flow that checks tokenexpiresat before each request. ^[8]
• Empty parameter dictionary vs. None. All three endpoints accept p as an optional dictionary. Passing None is valid and returns unfiltered results, but if you intend to filter by department or date range, ensure the dictionary is correctly formed — a malformed dict will be ignored rather than raising an obvious error. ^[1][2][4]
• Scope changes require token re-issuance. Adding Desk.basic.READ to your config after initial authorisation does not automatically update existing tokens. Users or service accounts must re-authenticate to receive a token that includes the new scope. ^[5]

---

What to check

• Scopes are active on the current token — verify that Desk.basic.READ (and any other required scopes) appear in the token's granted scope list before making your first metrics call. ^[5]
• All three endpoints return data — confirm that getagentperformancemetrics, getagentstatusmonitoring, and getagentskill_mapping each respond with a non-empty payload, as a missing response from any one of them usually points to a permission or parameter issue. ^[1][2][4]
• Token refresh logic is working — check that your integration correctly reads tokenexpiresat and re-fetches credentials before they lapse, so scheduled metric pulls do not fail overnight. ^[8]