Zoho Desk's REST API exposes three dedicated endpoints that let you retrieve time entry data for any agent — either as a full list, a single record, or filtered by billing type.
Why this matters
When you need to audit how agents are spending their time, generate billing reports, or feed time-tracking data into an external system, you must be able to query agent time entries programmatically. Zoho Desk provides purpose-built API operations for exactly this use case, and knowing which endpoint to call — and with which parameters — saves significant development effort.
> Beam Help is an independent expert support resource for Zoho products and is not official Zoho support.
---
Step-by-step
Step 1. Identify the agent whose time entries you need.
Every request requires an agentId. This is the unique identifier for the agent record inside your Zoho Desk organisation. You can obtain it from the Agents section of your Desk admin panel or from a prior API call that returns agent objects. Keep this value handy — it appears in the URL path for all three operations below. [5]
Step 2. List all time entries for an agent.
Send a GET request to the following path, substituting the agent's identifier:
GET /api/v1/agents/{agentId}/timeEntriesThe operation is named listagenttime_entries. An optional p parameter object lets you pass query-string filters (such as pagination or date range) alongside the request. In Python the call looks like this:
client.list_agent_time_entries(agentId="12345678", p={"from": 1, "limit": 50})This returns the full collection of time entries recorded against that agent. [5]
Step 3. Retrieve a single, specific time entry.
If you already know the identifier of a particular time entry — for example, from the list returned in Step 2 — you can fetch just that record with:
GET /api/v1/agents/{agentId}/timeEntries/{timeEntryId}The operation is named getagenttime_entry and requires both agentId and timeEntryId as path parameters. The optional p dict can carry any additional query parameters your integration needs. [7]
client.get_agent_time_entry(agentId="12345678", timeEntryId="98765432")Step 4. Filter time entries by billing type.
When you only want entries that match a specific billing classification (for example, billable vs. non-billable), use the billing-type variant of the endpoint:
GET /api/v1/agents/{agentId}/timeEntries/billingTypeThe operation is named getagenttimeentriesby. Pass the desired billing type through the p parameter dictionary. This is particularly useful when generating invoices or reconciling billable hours. [3]
client.get_agent_time_entries_by(agentId="12345678", p={"type": "Billable"})Step 5. Handle the response.
All three endpoints return JSON. Parse the response body to extract the time entry fields you need — such as duration, ticket reference, and billing classification — and map them into your reporting or billing workflow. [5][7][3]
---
Common pitfalls
- Wrong
agentIdformat. Passing a display name or email instead of the numeric agent ID will result in a 404 or empty response. Always resolve the agent ID from the API before constructing your request. [5] - Confusing the billing-type endpoint with the list endpoint. The path
/timeEntries/billingTypeis a distinct route, not a sub-resource of a specific entry. Do not insert atimeEntryIdbetweentimeEntriesandbillingType. [3] - Missing pagination parameters. The list endpoint (
/timeEntries) may return a paginated result set. If you omit pagination controls in thepdict, you may only receive the first page of entries and silently miss older records. [5]
---
What to check
- Confirm that the
agentIdyou are using resolves to an active agent in your Zoho Desk organisation before making bulk requests. - Verify that your API credentials carry the Time Entry read permission scope; without it, all three endpoints will return an authorisation error.
- After retrieving entries, cross-reference at least one record against the Zoho Desk UI (agent profile → time entries) to confirm the data matches what is displayed in the portal. [5][7][3]