How to get active timer for agent in Zoho Desk

Retrieving an active timer for a specific agent in Zoho Desk is straightforward via the REST API — a single authenticated GET request returns the currently running timer associated with that agent.

Why this matters

When building dashboards, automations, or integrations around Zoho Desk time-tracking, you often need to know whether an agent already has a timer running before starting a new one. Polling the active timer endpoint lets your integration avoid duplicate entries and gives supervisors real-time visibility into agent activity. This is especially useful in billing workflows or SLA-monitoring tools that depend on accurate time data.

Step-by-step

Step 1. Identify the agent's ID.

Before making the call, locate the agentId for the agent you want to query. You can retrieve this from the Zoho Desk Agents API or from the agent's profile in the Zoho Desk admin panel. Store this value — you will embed it directly in the request path. ^[1]

Step 2. Construct the request URL.

The endpoint follows this pattern:

GET /api/v1/agents/{agentId}/activeTimer

Replace {agentId} with the actual numeric or string identifier for the agent. The base URL for your org will depend on your data centre (e.g., https://desk.zoho.com for US, https://desk.zoho.eu for EU). ^[1]

Step 3. Authenticate your request.

All Zoho Desk API calls require a valid OAuth 2.0 access token passed in the Authorization header:

Authorization: Zoho-oauthtoken <your_access_token>

Ensure the OAuth scope you have granted covers Desk's time-tracking resources. ^[1]

Step 4. Send the GET request.

Issue the request with any optional query parameters passed as a dictionary (the p parameter in the SDK). A minimal Python example using the Zoho Desk SDK looks like this:

response = desk_client.get_active_timer_for_an(
    agentId="1234567890",
    p=None          # add query params here if needed
)
print(response)

The method internally fires GET /api/v1/agents/{agentId}/activeTimer and returns the active timer object for that agent. ^[1]

Step 5. Parse the response.

A successful response will contain the details of the currently running timer for the specified agent. If no timer is active, the API will typically return an empty result or a relevant status indicator. Handle both cases in your integration logic to avoid runtime errors. ^[1]

Step 6 (Optional). Retrieve the active timer for a task instead.

If your use case is task-centric rather than agent-centric, a parallel endpoint exists:

GET /api/v1/tasks/{taskId}/activeTimer

This follows the same authentication and parameter pattern, substituting taskId for agentId. ^[3]

response = desk_client.get_active_timer_for_a_2(
    taskId="9876543210",
    p=None
)

Use this when you need to check whether a timer is running on a specific task, regardless of which agent started it. ^[3]

---

Common pitfalls

• Wrong data centre base URL. Zoho Desk hosts data in multiple regions. Using the US endpoint when your org is on the EU or IN data centre will return authentication or "org not found" errors. Always confirm your org's data centre before hardcoding the base URL. ^[1]
• Expired or insufficient OAuth scope. If your access token does not include the correct Desk time-tracking scope, the API will return a 401 or 403. Re-generate your token with the appropriate scopes enabled. ^[1]
• Confusing agent timer vs. task timer. The agent-level endpoint (/agents/{agentId}/activeTimer) and the task-level endpoint (/tasks/{taskId}/activeTimer) serve different purposes. Calling the wrong one will return unexpected empty results rather than an error, which can be misleading during debugging. ^[1][3]
• Passing None vs. an empty dict for p. Some SDK versions handle None and {} differently when building query strings. If you experience unexpected behaviour, try passing an explicit empty dictionary instead. ^[1]

---

What to check

• Confirm the agentId is valid by cross-referencing it against the Zoho Desk Agents list endpoint before calling the active timer endpoint.
• Verify the OAuth token is current and has not expired — Zoho access tokens typically last one hour and must be refreshed using your refresh token.
• Test both the agent and task timer endpoints in a staging environment to confirm your parsing logic handles both "timer found" and "no active timer" response shapes correctly. ^[1][3]

---

> Beam Help is an independent expert support resource for Zoho products and is not official Zoho support. For platform-level issues or billing queries, contact Zoho directly through your account portal.