Agents - Get

Get information about an agent.

GET https://dev.azure.com/{organization}/_apis/distributedtask/pools/{poolId}/agents/{agentId}?api-version=6.0
GET https://dev.azure.com/{organization}/_apis/distributedtask/pools/{poolId}/agents/{agentId}?includeCapabilities={includeCapabilities}&includeAssignedRequest={includeAssignedRequest}&includeLastCompletedRequest={includeLastCompletedRequest}&propertyFilters={propertyFilters}&api-version=6.0

URI Parameters

Name In Required Type Description
agentId
path True
  • integer
int32

The agent ID to get information about

organization
path True
  • string

The name of the Azure DevOps organization.

poolId
path True
  • integer
int32

The agent pool containing the agent

api-version
query True
  • string

Version of the API to use. This should be set to '6.0' to use this version of the api.

includeAssignedRequest
query
  • boolean

Whether to include details about the agent's current work

includeCapabilities
query
  • boolean

Whether to include the agent's capabilities in the response

includeLastCompletedRequest
query
  • boolean

Whether to include details about the agents' most recent completed work

propertyFilters
query
  • string
array (string)

Filter which custom properties will be returned

Responses

Name Type Description
200 OK

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

Demand
IdentityRef
JObject

Represents a JSON object.

JToken

Represents an abstract JSON token.

PackageVersion
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.

TaskAgent

A task agent.

TaskAgentAuthorization

Provides data necessary for authorizing the agent using OAuth 2.0 authentication flows.

TaskAgentCloudRequest
TaskAgentDelaySource
TaskAgentJobRequest

A job request for an agent.

TaskAgentPoolOptions

Additional pool settings and details

TaskAgentPoolReference
TaskAgentPoolType

Gets or sets the type of the pool

TaskAgentPublicKey

Represents the public key portion of an RSA asymmetric key.

TaskAgentReference

A reference to an agent.

TaskAgentStatus

Whether or not the agent is online.

TaskAgentUpdate

Details about an agent update.

TaskAgentUpdateReason
TaskAgentUpdateReasonType
TaskOrchestrationOwner
TaskResult

The result of this request.

Demand

Name Type Description
name
  • string
value
  • string

IdentityRef

Name Type Description
_links

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.

JObject

Represents a JSON object.

Name Type Description
item

Represents an abstract JSON token.

type
  • string

Gets the node type for this JToken.

JToken

Represents an abstract JSON token.

Name Type Description
first

Get the first child token of this token.

hasValues
  • boolean

Gets a value indicating whether this token has child tokens.

item

Represents an abstract JSON token.

last

Get the last child token of this token.

next

Gets the next sibling token of this node.

parent
  • string

Gets or sets the parent.

path
  • string

Gets the path of the JSON token.

previous

Gets the previous sibling token of this node.

root

Gets the root JToken of this JToken.

type
  • string

Gets the node type for this JToken.

PackageVersion

Name Type Description
major
  • integer
minor
  • integer
patch
  • integer

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.

TaskAgent

A task agent.

Name Type Description
_links

The class to represent a collection of REST reference links.

accessPoint
  • string

This agent's access point.

assignedAgentCloudRequest

The agent cloud request that's currently associated with this agent.

assignedRequest

The request which is currently assigned to this agent.

authorization

Authorization information for this agent.

createdOn
  • string

Date on which this agent was created.

enabled
  • boolean

Whether or not this agent should run jobs.

id
  • integer

Identifier of the agent.

lastCompletedRequest

The last request which was completed by this agent.

maxParallelism
  • integer

Maximum job parallelism allowed for this agent.

name
  • string

Name of the agent.

osDescription
  • string

Agent OS.

pendingUpdate

Pending update for this agent.

properties

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.

provisioningState
  • string

Provisioning state of this agent.

status

Whether or not the agent is online.

statusChangedOn
  • string

Date on which the last connectivity status change occurred.

systemCapabilities
  • object
userCapabilities
  • object
version
  • string

Agent version.

TaskAgentAuthorization

Provides data necessary for authorizing the agent using OAuth 2.0 authentication flows.

Name Type Description
authorizationUrl
  • string

Endpoint used to obtain access tokens from the configured token service.

clientId
  • string

Client identifier for this agent.

publicKey

Public key used to verify the identity of this agent.

TaskAgentCloudRequest

Name Type Description
agent

A reference to an agent.

agentCloudId
  • integer
agentConnectedTime
  • string
agentData

Represents a JSON object.

agentSpecification

Represents a JSON object.

pool
provisionRequestTime
  • string
provisionedTime
  • string
releaseRequestTime
  • string
requestId
  • string

TaskAgentDelaySource

Name Type Description
delays
  • string[]
taskAgent

A reference to an agent.

TaskAgentJobRequest

A job request for an agent.

Name Type Description
agentDelays
agentSpecification

Represents a JSON object.

assignTime
  • string

The date/time this request was assigned.

data
  • object

Additional data about the request.

definition

The pipeline definition associated with this request

demands

A list of demands required to fulfill this request.

expectedDuration
  • string
finishTime
  • string

The date/time this request was finished.

hostId
  • string

The host which triggered this request.

jobId
  • string

ID of the job resulting from this request.

jobName
  • string

Name of the job resulting from this request.

lockedUntil
  • string

The deadline for the agent to renew the lock.

matchedAgents

A reference to an agent.

matchesAllAgentsInPool
  • boolean
orchestrationId
  • string
owner

The pipeline associated with this request

planGroup
  • string
planId
  • string

Internal ID for the orchestration plan connected with this request.

planType
  • string

Internal detail representing the type of orchestration plan.

poolId
  • integer

The ID of the pool this request targets

queueId
  • integer

The ID of the queue this request targets

queueTime
  • string

The date/time this request was queued.

receiveTime
  • string

The date/time this request was receieved by an agent.

requestId
  • integer

ID of the request.

reservedAgent

The agent allocated for this request.

result

The result of this request.

scopeId
  • string

Scope of the pipeline; matches the project ID.

serviceOwner
  • string

The service which owns this request.

statusMessage
  • string
userDelayed
  • boolean

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

TaskAgentPoolReference

Name Type Description
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

Additional pool settings and details

poolType

Gets or sets the type of the pool

scope
  • string
size
  • integer

Gets the current size of the pool.

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

TaskAgentPublicKey

Represents the public key portion of an RSA asymmetric key.

Name Type Description
exponent
  • string[]

Gets or sets the exponent for the public key.

modulus
  • string[]

Gets or sets the modulus for the public key.

TaskAgentReference

A reference to an agent.

Name Type Description
_links

The class to represent a collection of REST reference links.

accessPoint
  • string

This agent's access point.

enabled
  • boolean

Whether or not this agent should run jobs.

id
  • integer

Identifier of the agent.

name
  • string

Name of the agent.

osDescription
  • string

Agent OS.

provisioningState
  • string

Provisioning state of this agent.

status

Whether or not the agent is online.

version
  • string

Agent version.

TaskAgentStatus

Whether or not the agent is online.

Name Type Description
offline
  • string
online
  • string

TaskAgentUpdate

Details about an agent update.

Name Type Description
currentState
  • string

Current state of this agent update.

reason

Reason for this update.

requestTime
  • string

Date on which this update was requested.

requestedBy

Identity which requested this update.

sourceVersion

Source agent version of the update.

targetVersion

Target agent version of the update.

TaskAgentUpdateReason

Name Type Description
code

TaskAgentUpdateReasonType

Name Type Description
downgrade
  • string
manual
  • string
minAgentVersionRequired
  • string

TaskOrchestrationOwner

Name Type Description
_links

The class to represent a collection of REST reference links.

id
  • integer
name
  • string

TaskResult

The result of this request.

Name Type Description
abandoned
  • string
canceled
  • string
failed
  • string
skipped
  • string
succeeded
  • string
succeededWithIssues
  • string