Get Build Details
In this article, we explore common use cases of retrieving build data via REST API. These are helpful when you need to:
Retrieve finished or queued builds.
Locate builds by certain condition.
Look up dependencies and changes.
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
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 Specific Builds
BuildLocator can accept many other dimensions. Some of them include:
id:<internal build id>— use internal build ID when you need to refer to a specific build.
number:<build number>— to find build by build number, provided build configuration is already specified.
project:<project locator>— limit the list to the builds of the project found under ProjectLocator (belonging to any build type directly under the project).
affectedProject:<project locator>— limit the list to the builds of the project found under ProjectLocator (belonging to any build type directly or indirectly under the project).
buildType:(<buildTypeLocator>),defaultFilter:false— all the builds of the build configuration found under BuildTypeLocator.
tag:<tag>— get tagged builds. If a list of tags is specified, for example,
tag:<tag1>, tag:<tag2>, only the builds containing all the specified tags are returned.
status:<SUCCESS/FAILURE/UNKNOWN>— list builds with the specified status only.
user:(<userLocator>)— limit builds to only those triggered by the user found under UserLocator.
personal:<true/false/any>— limit builds by the personal flag. By default, personal builds are not included.
canceled:<true/false/any>— limit builds by the canceled flag. By default, canceled builds are not included.
failedToStart:<true/false/any>— limit builds by the failed to start flag. By default, failed to start builds are not included.
state:<queued/running/finished>— limit builds by the specified state.
running:<true/false/any>— limit builds by the running flag. By default, running builds are not included.
state:running,hanging:true— fetch hanging builds.
pinned:<true/false/any>— limit builds by the pinned flag.
branch:<branch locator>— limit the builds by branch. BranchLocator can be the branch name displayed in the UI, or
(name:<name>,default:<true/false/any>,unspecified:<true/false/any>,branched:<true/false/any>). By default, only builds from the default branch are returned. To retrieve all builds, add the following locator:
branch:default:any. The whole endpoint will look like this:GET /app/rest/builds/?locator=buildType:MyBuildConfigurationID,branch:default:any.
revision:<REVISION>— find builds by revision, for example, this endpoint will return all builds of the given build configuration with the revision:GET /app/rest/builds?locator=revision:(MyRevision),buildType:(id:MyBuildConfigurationID)
agentName:<name>— agent name to return only builds ran on the agent with the specified name.
sinceBuild:(<buildLocator>)— limit the list of builds only to those after the one specified (using another nested BuildLocator).
sinceDate:<date>— limit the list of builds only to those started after the date specified. The date should be in the same format as dates returned by REST API (for example, 20130305T170030+0400).
queuedDate/startDate/finishDate:(date:<time-date>,build:<build locator>,condition:<before/after>)— filter builds based on the time specified by the BuildLocator, for example for the builds finished after November 23, 2017, 20:34:46, GMT+1 timezone use:GET /app/rest/builds?locator=finishDate:(date:20171123T203446%2B0100,condition:after)
count:<number>— serve only the specified number of builds.
start:<number>— list the builds from the list starting from the position specified (zero-based).
lookupLimit:<number>— limit processing to the latest N builds only (the default is 5000). If none of the latest N builds match the other specified criteria of the build locator, 404 response is returned for single build request and empty collection for multiple builds request. See the related note.
Get Queued Builds
To get all queued builds, use:
The endpoint responds with an instance of a Builds entity. The request can be limited further by using BuildQueueLocator. For example, to get all queued builds in specific configuration:
or fetch details of specific queued build:
This may be useful to find out what agents are compatible with the queued build:
The response is formatted as Agents.
Changes entity is meant to represent changes the same way as displayed in the build's Changes in TeamCity UI. In most cases, these are the commits between the current and previous build. The
changes node is not included in the build by default, and it has the
href attribute only. If you execute the request specified in
href, you will get the required changes.
To get all changes associated with a certain build, use:
locator is typed as ChangeLocator.
To get details on a specific change, use:
For any file within a change, you can address
changeType to find out if the file was
This requests returns changes for a
To find any changes since a specific change under a build configuration
Finally, to find all pending changes under a build configuration, use:
Get Builds with Specific Revision
To get all builds with a specific revision, use:
Get Dependency/Dependent Builds
To get builds which have a snapshot dependency on a given build, use:
To get builds which are a target of snapshot dependency on a given build, use:
To get builds which have an artifact dependency on a given build, use:
To get builds which are a target of an artifact dependency on a given build, use: