Azure DevOps Get Agent Pools API response doesn't include all available agent pools

Question

I'm trying to get a list of available agent pools using the REST API:

GET https://dev.azure.com/{organization}/_apis/distributedtask/pools?api-version=7.1

from an Azure Classic pipeline using $(System.AccessToken):

POOL_API_URL="https://dev.azure.com/$AZURE_DEVOPS_ORG/_apis/distributedtask/pools?api-version=7.1"
RESPONSE=$(curl -H "Authorization: Bearer $AZURE_AUTH_TOKEN" "$POOL_API_URL")
echo $RESPONSE

The API call succeeds, but the response is missing some of the agent pools.

I assume that some permissions are missing for the other agent pools. Could you please clarify what permissions are required for an agent pool so that it can be listed with the API above?

Answer 1

The list of agent pools returned by the REST API (or by az pipelines pool list) is filtered by the permissions of the identity used to call it. To see an agent pool in the API response, the calling identity must have permission to use or manage that pool.

In Azure DevOps, these permissions are controlled by:

1. Agent pool security (roles on the pool)
   On each agent pool, membership in roles such as Administrator (and other roles that imply Manage/Use permissions) determines whether the pool is visible and manageable. The Security action on the Agent pools tab controls the security of all project agent pools, and role memberships for individual project agent pools are inherited from there. By default, Build Administrators, Release Administrators, and Project Administrators are added to the Administrator role of All agent pools.
2. Pipeline permissions for the pool (YAML pipelines)
   Pipeline permissions control which YAML pipelines are authorized to use a given agent pool. If a pool is locked down, only selected YAML pipelines can use it; other YAML pipelines trigger an authorization request that an Agent pool Administrator must approve. While these permissions mainly govern use of the pool by YAML pipelines, they also reflect which identities are allowed to interact with the pool.
3. Organization/project-level permissions
   Permissions such as Manage build queues are required to configure certain aspects of agent pools (for example, maintenance job settings). Lack of these permissions can prevent viewing or managing specific pools or their settings.

When calling the REST API from a classic pipeline using $(System.AccessToken), the effective permissions are those of the build service identity for that project. If that identity does not have at least Use (and, depending on scenario, Manage) permission on some agent pools, those pools will not appear in the API response.

To ensure all desired pools appear in the API response:

1. Go to Project settings → Agent pools (or Organization settings → Pipelines → Agent pools for organization pools).
2. Open Security for All agent pools and/or for each specific pool that is missing from the API response.
3. Add the relevant build service identity (or a group it belongs to) to a role that grants Use/Manage on that pool (for example, Administrator, or another role with equivalent permissions).
4. If using YAML pipelines, verify Pipeline permissions for the pool so that the pipeline using $(System.AccessToken) is allowed to use that pool.

Once the calling identity has appropriate agent pool permissions, the REST API will list those pools.

---

References:

• Create and manage agent pools
• az pipelines pool list
• az pipelines pool show