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:
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:
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:
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:
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:
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:
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:
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).