Listing agents by profile in Zoho Desk is done via a single authenticated GET request to the Desk REST API, passing the target profile's ID as a path parameter.
Why this matters
When you manage a multi-team support operation, agents are grouped into profiles that control their permissions and access levels. Being able to programmatically retrieve every agent belonging to a specific profile lets you audit team composition, automate onboarding checks, or feed agent data into external dashboards — all without manually browsing the Zoho Desk UI.
Step-by-step
Step 1. Identify the profile_id for the profile whose agents you want to retrieve. You can find this value through the Zoho Desk admin panel under agent profile settings, or by querying the profiles endpoint first. The ID is a string value that uniquely identifies the profile within your Desk portal. [1]
Step 2. Construct your HTTP request. The endpoint follows this pattern:
GET /api/v1/profiles/{profile_id}/agentsReplace {profile_id} with the actual profile identifier you collected in Step 1. [1]
Step 3. Add your authentication headers. Zoho Desk's API requires a valid OAuth 2.0 access token passed as a Bearer token in the Authorization header. Ensure your OAuth scope covers agent and profile read operations before making the call. [1]
Step 4. Optionally include the p query parameter to control pagination. This parameter lets you specify which page of results to return when the profile contains a large number of agents. If omitted, the API returns the first page by default. [1]
Step 5. Send the request and parse the response. A successful call returns a JSON payload listing the agents associated with that profile. If you are using Python, the call can be structured like this:
def list_agents_by_profile(self, profile_id: str, p: dict = None):
"""List agents by profile"""
return self.c.request("GET", f"/api/v1/profiles/{profile_id}/agents", p, None)The p argument maps directly to any query parameters (such as the page number) you want to pass along. [1]
Step 6. If your use case also requires listing agents by their assigned *role* rather than their profile, a separate endpoint is available:
GET /api/v1/roles/{role_id}/agentsThis operation accepts a role_id path parameter and an optional p pagination parameter, following the same pattern as the profile-based lookup. [8]
Common pitfalls
- Wrong ID type. Profile IDs and role IDs are distinct. Passing a role ID to the
/profiles/endpoint (or vice versa) will return an error or empty results. Double-check which identifier you are using before making the call. [^1, ^8] - Missing pagination handling. If a profile has many agents, the API will paginate results. Failing to iterate through pages using the
pparameter means your application will only see a partial list. [1] - Insufficient OAuth scope. If your access token was generated without the correct Desk API scopes, the request will be rejected with an authorisation error. Regenerate the token with the appropriate read permissions for agents and profiles. [1]
What to check
- Confirm that the
profile_idyou are using actually exists in your Zoho Desk account and corresponds to the correct profile before calling the endpoint. [1] - Verify that your response includes the expected number of agents; if the count seems low, check whether you need to request additional pages via the
pparameter. [1] - If you also manage agents by role, ensure you are calling
/api/v1/roles/{roleid}/agentswith a validroleidwhen role-based lookups are needed, keeping the two endpoints clearly separated in your integration logic. [8]
---
*Beam Help is an independent expert support resource for Zoho products and is not official Zoho support. Always refer to Zoho's own documentation for the most current API specifications.*