How to retrieve a ticket timer in Zoho Desk

Retrieving a ticket timer in Zoho Desk is straightforward using the REST API — you can fetch either the full timer record or only the currently running (active) timer for any given ticket.

Why this matters

When your support team tracks time spent on tickets, you may need to programmatically read timer data — for reporting dashboards, billing integrations, or automation workflows. Zoho Desk exposes dedicated endpoints for both the complete timer and the active timer, so you can choose the right one depending on whether you need a snapshot of all recorded time or just what is currently ticking. As independent expert support (not official Zoho support), Beam Help walks you through both options below.

---

Step-by-step

Step 1. Authenticate and obtain a valid access token.

Before calling any Zoho Desk endpoint, your integration must hold a valid OAuth 2.0 access token. If your token has expired, the system will use your stored refresh token to request a new one automatically — the refresher exchanges the refreshtoken against the token URL using your clientid and clientsecret, then stores the updated accesstoken and its expiry timestamp for future calls. ^[8]

Step 2. Initialise the Zoho Desk API client.

Instantiate a ZohoDeskClient with your API domain, current access token, and organisation ID (orgid). Wrap it in a ZohoDeskApi instance. If your orgid is not yet stored, the client can auto-discover it by calling the organisations endpoint and persisting the first result. ^[7]

Step 3. Retrieve the full ticket timer.

Call the GET /api/v1/tickets/{ticketId}/timer endpoint, substituting the real ticket identifier for {ticketId}. In Python, this looks like:

result = api.get_ticket_timer(ticketId="your_ticket_id")

The method issues a GET request to /api/v1/tickets/{ticketId}/timer and returns the timer record associated with that ticket. An optional p parameter can carry additional query-string arguments if needed. ^[1]

Step 4. (Alternative) Retrieve only the active timer.

If you only care about a timer that is currently running — for example, to display a live elapsed-time indicator — use the active-timer endpoint instead:

result = api.get_active_timer_for_a(ticketId="your_ticket_id")

This issues a GET request to /api/v1/tickets/{ticketId}/activeTimer and returns data exclusively for the timer that is presently in a running state. ^[2]

Step 5. Handle the response.

Both endpoints return a dictionary. Inspect the result for timer fields such as duration, status, and agent details. If the ticket has no active timer when you call the activeTimer endpoint, expect an empty or null data payload rather than an error.

---

Common pitfalls

• Missing or stale orgid: Zoho Desk requires the organisation ID to be passed as a header or parameter on every request. If orgid is blank, the client will attempt auto-discovery, but this adds latency. Always persist the org_id after the first successful call. ^[7]

• Expired access tokens: Tokens typically expire after 3,600 seconds. If you receive an authentication error, verify that your token-refresh logic is correctly updating both accesstoken and tokenexpires_at in your data store. ^[8]

• Confusing the two timer endpoints: GET .../timer returns the full timer record (including historical data), while GET .../activeTimer returns only what is currently running. ^[1][2] Using the wrong one can result in empty responses that look like errors.

• Updating or resetting by mistake: If you need read-only access, be careful not to accidentally call PATCH /api/v1/tickets/{ticketId}/timer (which modifies the timer) ^[4] or POST /api/v1/tickets/{ticketId}/timer/reset (which resets it entirely). ^[6] Keep your HTTP method strictly as GET for retrieval.

---

What to check

• Confirm the ticketId is valid — verify it exists in your Zoho Desk portal before making the API call, as an invalid ID will return a not-found error rather than timer data.
• Verify your OAuth scopes — ensure the access token was granted the Desk time-tracking read scope; missing scopes will produce a permissions error even with a valid token. ^[5]
• Inspect the response structure — confirm the returned dictionary contains the expected timer fields before passing the data downstream, since an inactive ticket may return a minimal or empty timer object. ^[1][2]