TeamCity REST API Reference
 
2023.05
You are viewing the documentation for an earlier version of TeamCity REST API Reference.
  1. Common Use Cases
  2. Manage Builds
  3. Get Build Statistics

Get Build Statistics

Last modified: 21 February 2023

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
/app/rest/builds/<buildLocator>/statistics/

where buildLocator is a BuildLocator entity. The endpoint responds with a Properties entity.

You can fetch any specific values directly via:

GET
/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
/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
/app/rest/builds?locator=agent:(id:<agent ID>)

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

GET
/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 /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 /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
/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).