Pools - Get Agent Pools

Get a list of agent pools.

GET https://dev.azure.com/{organization}/_apis/distributedtask/pools?api-version=6.1-preview.1
GET https://dev.azure.com/{organization}/_apis/distributedtask/pools?poolName={poolName}&properties={properties}&poolType={poolType}&actionFilter={actionFilter}&api-version=6.1-preview.1

URI Parameters

Name In Required Type Description
organization
path True

string

The name of the Azure DevOps organization.

api-version
query True

string

Version of the API to use. This should be set to '6.1-preview.1' to use this version of the api.

actionFilter
query

TaskAgentPoolActionFilter

Filter by whether the calling user has use or manage permissions

poolName
query

string

Filter by name

poolType
query

TaskAgentPoolType

Filter by pool type

properties
query

string

array (string)

Filter by agent pool properties (comma-separated)

Responses

Name Type Description
200 OK

TaskAgentPool[]

successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name Description
vso.agentpools Grants the ability to view tasks, pools, queues, agents, and currently running or recently completed jobs for agents

Definitions

Name Description
IdentityRef
PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

ReferenceLinks

The class to represent a collection of REST reference links.

TaskAgentPool

An organization-level grouping of agents.

TaskAgentPoolActionFilter

Filter by whether the calling user has use or manage permissions

TaskAgentPoolOptions

Additional pool settings and details

TaskAgentPoolType

Gets or sets the type of the pool

IdentityRef

Name Type Description
_links

ReferenceLinks

This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.

descriptor

string

The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.

directoryAlias

string

Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary

displayName

string

This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.

id

string

imageUrl

string

Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary

inactive

boolean

Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary

isAadIdentity

boolean

Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType)

isContainer

boolean

Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType)

isDeletedInOrigin

boolean

profileUrl

string

Deprecated - not in use in most preexisting implementations of ToIdentityRef

uniqueName

string

Deprecated - use Domain+PrincipalName instead

url

string

This url is the full route to the source resource of this graph subject.

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

Name Type Description
count

integer

The count of properties in the collection.

item

object

keys

string[]

The set of keys in the collection.

values

string[]

The set of values in the collection.

The class to represent a collection of REST reference links.

Name Type Description
links

object

The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

TaskAgentPool

An organization-level grouping of agents.

Name Type Description
agentCloudId

integer

The ID of the associated agent cloud.

autoProvision

boolean

Whether or not a queue should be automatically provisioned for each project collection.

autoSize

boolean

Whether or not the pool should autosize itself based on the Agent Cloud Provider settings.

autoUpdate

boolean

Whether or not agents in this pool are allowed to automatically update

createdBy

IdentityRef

Creator of the pool. The creator of the pool is automatically added into the administrators group for the pool on creation.

createdOn

string

The date/time of the pool creation.

id

integer

isHosted

boolean

Gets or sets a value indicating whether or not this pool is managed by the service.

isLegacy

boolean

Determines whether the pool is legacy.

name

string

options

TaskAgentPoolOptions

Additional pool settings and details

owner

IdentityRef

Owner or administrator of the pool.

poolType

TaskAgentPoolType

Gets or sets the type of the pool

properties

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

scope

string

size

integer

Gets the current size of the pool.

targetSize

integer

Target parallelism.

TaskAgentPoolActionFilter

Filter by whether the calling user has use or manage permissions

Name Type Description
manage

string

none

string

use

string

TaskAgentPoolOptions

Additional pool settings and details

Name Type Description
elasticPool

string

TaskAgentPool backed by the Elastic pool service

none

string

preserveAgentOnJobFailure

string

Set to true if agents are held for investigation after a TaskAgentJobRequest failure

singleUseAgents

string

Set to true if agents are re-imaged after each TaskAgentJobRequest

TaskAgentPoolType

Gets or sets the type of the pool

Name Type Description
automation

string

A typical pool of task agents

deployment

string

A deployment pool