How to get task timer in Zoho Desk

Task timers in Zoho Desk let you track time spent on individual tasks, and the Zoho Desk API exposes two distinct endpoints for retrieving that data — one for the full timer record and one for the currently running timer.

Why this matters

When you need to audit time logged against support tasks, build custom reporting dashboards, or integrate Zoho Desk task time data into a third-party billing tool, you must know which API endpoint to call and how to authenticate correctly. There are two separate read operations available: fetching the complete timer record for a task, and fetching only the *active* (currently running) timer. Choosing the wrong one can return empty data or a misleading response.

---

Step-by-step

Step 1. Confirm your OAuth scopes include task permissions.

Before making any timer request, verify that your connected Zoho Desk OAuth token was issued with at least Desk.tasks.READ (or Desk.tasks.ALL) in its scope list. Without this, the API will reject your request with an authorisation error. ^[5]

Step 2. Obtain a valid access token.

Your integration must hold a current access token for Zoho Desk. If the token has expired, use your stored refresh token to call Zoho's token endpoint with your clientid, clientsecret, and granttype: refreshtoken. A successful response will include a new accesstoken and an updated tokenexpires_at value. ^[6]

Step 3. Identify the taskId you want to query.

Every timer request is scoped to a specific task. You need the unique task identifier (e.g. "1234567890") before calling either endpoint. This is typically returned when you create or list tasks via the Zoho Desk API.

Step 4. Retrieve the full timer record for a task.

Send a GET request to:

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

Replace {taskId} with your actual task identifier. An optional query-parameter dictionary (p) can be passed for any supported filter or pagination arguments. In Python this looks like: ^[1]

response = desk_api.get_task_timer(taskId="1234567890")

This returns the complete timer record associated with that task, including historical time entries.

Step 5. Retrieve only the currently active timer (if any).

If you only need to know whether a timer is *running right now* on a task, call the dedicated active-timer endpoint instead:

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

Again, substitute your real taskId. In Python: ^[2]

response = desk_api.get_active_timer_for_a_2(taskId="1234567890")

This endpoint returns data only when a timer is actively running on the specified task. If no timer is in progress, expect an empty or null payload.

Step 6. (Optional) Update the timer if needed.

If the retrieved timer data needs correction — for example, adjusting logged time — you can follow up with a PATCH request to the same /api/v1/tasks/{taskId}/timer path, supplying a data dictionary with the fields to update. ^[7]

Step 7. Initialise the Desk API client with the correct org_id.

Zoho Desk is organisation-scoped. When building the API client, ensure the orgid is populated. If it is missing, the system can auto-discover it by calling the organisations list endpoint and persisting the first returned id. Without a valid orgid, all Desk API calls — including timer requests — will fail. ^[4]

---

Common pitfalls

• Calling the wrong endpoint. GET /api/v1/tasks/{taskId}/timer returns the full timer history, while GET /api/v1/tasks/{taskId}/activeTimer returns only a live, in-progress timer. ^[1][2] If you expect real-time status but call the former, you may see stale data.
• Missing or expired access token. The token refresh flow must complete successfully — specifically, the response must contain access_token — before any Desk API call is attempted. An error key in the refresh response means the token was not renewed. ^[6]
• Insufficient OAuth scopes. Requesting timer data requires task-level read permissions (Desk.tasks.READ or Desk.tasks.ALL). Scopes are set at the time of OAuth authorisation and cannot be added retroactively without re-authorising. ^[5]
• Missing orgid. Zoho Desk requires an organisation ID on every request. If your connection record does not have deskorg_id stored, the client must resolve it before proceeding. ^[4]

---

What to check

• Scope coverage: Confirm Desk.tasks.READ or Desk.tasks.ALL appears in your active OAuth scope configuration. ^[5]
• Token validity: Verify tokenexpiresat is in the future; if not, trigger a refresh before calling the timer endpoints. ^[6]
• Correct endpoint selection: Use /activeTimer for live status checks and /timer for full historical records, and confirm the taskId in the path matches the task you intend to query. ^[1][2]

---

*Beam Help is an independent expert support resource for Zoho products — we are not official Zoho support. For platform-level issues, always cross-reference the official Zoho Desk API documentation.*