TeamCity REST API Reference 2021.2 Help

Get Build Statistics

In this article, we explore common use cases of accessing build statistics via TeamCity REST API:

  • Getting statistics for analysis or demo.

  • Getting specific build details.

  • Configuring a complex build logic which requires metadata from the server.

Get Build Statistic Values

To get all build statistic values for a specific build, use:

GET http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/statistics/

The endpoint responds with a Properties entity.

You can fetch any specific values directly via:

GET http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/statistics/<value_name>

Get Agent Workload Statistics

The agent Statistics tab of the TeamCity UI shows when the agents were busy. It allows estimating how loaded your system is. It is possible to get the same information via TeamCity REST API.

To get the recent load time for a specific agent, you need to perform two steps. First, find out the agent ID:

GET http://<TeamCity Server host>:<port>/app/rest/agents

The server will respond with an Agents entity containing Agent entities. Parse out the agent's id property in this response and use it to send the following request:

GET http://<TeamCity Server host>:<port>/app/rest/builds?locator=agent:(id:<agent ID>)

To find out when exactly the builds were occupying this agent, specify the fields parameter:

GET http://<TeamCity Server host>:<port>/app/rest/builds?locator=agent:(id:<agent ID>)&fields=build(id,buildTypeId,queuedDate,startDate,finishDate)

The response will contain a timestamp with the details on when the agent was put to the queue, and when it was occupied and released by this build. You can use this data to calculate the total agent busy or idle time.

Get Build Details

For most cases when you need to get build details, the following request is sufficient:

GET http://<TeamCity Server host>:<port>/app/rest/builds/id:<build ID>

To get extra details, you can use sub-entities of Build. For example, the TestOccurrences entity, retrieved by the above call, is not expanded by default. To retrieve the details of the tests executed within the build, you can use the href property of the TestOccurrences entity. Alternatively, you can change the endpoint:

GET http://<TeamCity Server host>:<port>/app/rest/builds?locator=id:8501&fields=build(id,testOccurrences(testOccurrence(id,name,status,duration)))

This will expose the minimal data about the tests: name, status, duration, and so on.

Another method of retrieving the build statistics is to use the following endpoint:

GET http://<TeamCity Server host>:<port>/app/rest/builds/id:<build ID>/statistics

The response will contain a Properties entity with the statistical values for a build (the duration of build steps, summary on tests, and so on).

Last modified: 13 October 2021