Retrieving Agent Specification from Azure DevOps REST API Build Pipeline Definition

Question

How can the Azure DevOps REST API be used to retrieve the "vmImage/Agent Specification" from a build pipeline definition? The response currently includes the pool name and ID, but attempts to use various property filters have not yielded the desired information.

Answer 1

Hi Jeff Positano

Since you're working with Classic pipelines, and you're trying to retrieve the Agent Specification, The Azure DevOps REST API does NOT currently expose the "Agent Specification" (e.g., windows-latest, ubuntu-20.04) for Classic pipelines — even when using Microsoft-hosted agents.

In Classic pipelines, when you choose a Microsoft-hosted agent, you select an Agent pool e.g., Azure Pipelines, and then choose an "Agent Specification" e.g., windows-2022 via the UI dropdown.

However, this "Agent Specification" value is stored internally as a demand, but the Build Definitions API only returns the pool ID/name - it doesn't expose that capability.

For classic pipelines, the manual way to find the agent specification is Go to Azure DevOps -> Pipelines -> Pipeline -> Edit -> Triggers -> YAML Tab.

If you want to know what image was used in the most recent run, you can query the last build:

GET https://dev.azure.com/{org}/{project}/_apis/build/builds/{buildId}?api-version=7.1-preview.7

You can see the output as agentSpecification.identifier . It is only present if it was a Microsoft-hosted agent.

Additional References:

https://learn.microsoft.com/en-us/rest/api/azure/devops/build/Builds/Get?view=azure-devops-rest-7.1

Hope this helps!

Please Let me know if you have any queries.

If you found the information helpful, please click "Upvote" on the post to let us know and consider accepting the answer as the token of appreciation. Thank You.

Answer 2

Hi Jeff Positano

Could you please follow the below steps to retrieve Agent Specification:

1. Use the following API call to retrieve the build pipeline definition, this will return details about the pipeline, including the agent pool.

      GET https://dev.azure.com/{organization}/{project}/_apis/build/definitions/{definitionId}?api-version=7.1-preview.1
   

   Replace {organization}, {project}, and {definitionId} with your specific values.
2. Check YAML Configuration If your pipeline is defined using YAML, the vmImage is usually specified in the pool section:

      pool:
        vmImage: 'ubuntu-latest'
   

   Unfortunately, the REST API does not always expose this directly.
3. You can retrieve details about the agent pool using the below API, but this provides information about the pool and id but may not include the exact vmImage.

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

4. Alternatively, you might retrieve the vmImage using PowerShell:

      $organization = "your_organization"
      $project = "your_project"
      $definitionId = "your_definition_id"
      $personalAccessToken = "your_pat"
      $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$($personalAccessToken)"))
      $response = Invoke-RestMethod -Uri "https://dev.azure.com/$organization/$project/_apis/build/definitions/$definitionId?api-version=7.1-preview.1" `
          -Method Get `
          -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}
      $vmImage = $response.queue.pool.vmImage
      Write-Output "VM Image: $vmImage"
   

Hope this helps!

Please Let me know if you have any queries.

Answer 3

Thank you for the examples. I've tried all of them and the responses are still not showing the values. Also, not all of our pipelines are YAML but are "classic", so I need the "Agent Specification" value when the pipeline is configured to use the Microsoft hosted agent.