How to list agents by role in Zoho Desk

Listing agents by role in Zoho Desk is straightforward via the REST API — a single authenticated GET request against the roles endpoint returns every agent assigned to a given role.

Why this matters

When you manage a large support team, you often need to audit which agents hold a particular role, automate onboarding workflows, or feed role-based agent lists into external dashboards. Doing this programmatically through the Zoho Desk API saves significant manual effort compared to browsing the admin UI one role at a time. As independent expert support for Zoho (Beam Help — not official Zoho support), we see this use case frequently in enterprise Desk deployments.

Step-by-step

Step 1. Obtain your role_id.

Before you can query agents, you need the unique identifier of the role you want to inspect. You can retrieve role IDs from your Zoho Desk admin panel under user management, or by calling the roles list endpoint first. Keep this value handy — it slots directly into the request path. ^[1]

Step 2. Authenticate your API client.

All Zoho Desk API calls require a valid OAuth 2.0 access token scoped to your organisation. Ensure your token has the necessary Desk permissions before proceeding. ^[1]

Step 3. Send the GET request to the agents-by-role endpoint.

Issue an HTTP GET to the following path, substituting your actual role identifier:

GET /api/v1/roles/{role_id}/agents

This operation — named listagentsby_role internally — returns the collection of agents associated with that role. ^[1]

Step 4. Handle pagination with the p parameter.

The endpoint accepts an optional p parameter for pagination. If your role contains a large number of agents, increment p (e.g., p=1, p=2) and repeat the request until you receive an empty or partial result set, indicating you have reached the final page. ^[1]

Step 5. Parse and use the response.

The response body contains the agent records tied to the specified role. You can pipe this data into reports, sync it with another system, or use it to drive downstream automation logic. ^[1]

Step 6 (optional). Wrap the call in a reusable function.

If you are working in Python, a clean pattern is to encapsulate the request so it can be called with just a role_id and an optional params dictionary:

def list_agents_by_role(self, role_id: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/roles/{role_id}/agents", p, None)

This keeps your integration tidy and makes pagination easy to layer on top. ^[1]

Common pitfalls

• Wrong role_id format. Passing a role *name* instead of the numeric or string ID will result in a 404 or empty response. Always resolve the ID programmatically rather than hard-coding a display name. ^[1]
• Missing pagination. Omitting the p parameter and assuming the first response is exhaustive can cause you to miss agents when a role has more members than the default page size. Always loop until the result set is empty. ^[1]
• Scope mismatch. If your OAuth token lacks the correct Desk API scope, the endpoint will return an authorisation error rather than agent data. Double-check your token's granted scopes before debugging the request itself. ^[1]

What to check

• Confirm the role_id is valid by cross-referencing it against the roles list in Zoho Desk's admin settings before running the query.
• Verify pagination is complete by checking whether the final page returns fewer records than the page size, confirming you have retrieved all agents.
• Validate agent count against the number shown in the Zoho Desk UI for that role to ensure the API response and the admin panel are in agreement. ^[1]