TeamCity REST API 2020.2 Help

Get Build Statistics

In this article, we explore common use cases of accessing build statistics via REST API. These are helpful when you need to:

  • Get statistics for analysis or demo

  • Get specific build details

  • Configure complex build logic which requires metadata from the server

See also general info about build statistics' requests.

Get recent builds

To get last 100 builds, run:

[GET] http://<TeamCity URL>:<port>/app/rest/builds

The server will respond with a Builds entity containing up to last 100 Build entities. This corresponds to the defaultFilter dimension logic described in the BuildLocator article. As a result, only successful non-personal builds started on the default branch would be represented in the response. To ignore this default filter and get any recent builds, run:

[GET] http://<TeamCity URL>:<port>/app/rest/builds?locator=defaultFilter:false

The endpoint response is paginated. Use nextHref or prevHref properties of Builds to navigate the response pages. Alternatively, you can control which builds are returned with the count (number of returned builds) and start (position of the first returned build) dimensions:

[GET] http://<TeamCity URL>:<port>/app/rest/builds?locator=count:10,start:15

In this example, the request will return 10 builds starting from the 15th element in the collection. Note that other dimensions in the request can affect the order and positions of the returned builds (for example, if you filter out currently running builds, the element at Nth position may change).

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 summary via REST API.

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

[GET] http://<TeamCity URL>:<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 URL>:<port>/app/rest/builds?locator=agent:(id:<agent ID>)

TeamCity will return a paginated collection of builds executed on this agent. As described in the previous use case, you can navigate the response pages.

To find out when exactly the builds were taking the agent's time, specify the fields parameter:

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

The reply will contain a timestamp with the details on when the agent was put to the queue, as well as when the agent 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 URL>:<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 may change the endpoint:

[GET] http://<TeamCity URL>:<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 URL>:<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: 22 December 2020