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:

/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:

/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:

/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 Specific Builds

The 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:

/app/rest/buildQueue

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:

/app/rest/buildQueue?locator=buildType(id:MyBuildConfigurationID)

or fetch details of specific queued build:

/app/rest/buildQueue?locator=id:<queued build ID>

This may be useful to find out what agents are compatible with the queued build:

/app/rest/buildQueue?locator=id:<queued build ID>/compatibleAgents

The response is formatted as Agents.

Get Changes

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:

/app/rest/changes?locator=build:(id:<buildId>)

locator is typed as ChangeLocator.

To get details on a specific change, use:

/app/rest/changes/id:changeId

For any file within a change, you can address changeType to find out if the file was added, edited, removed, copied, or unchanged.

This requests returns changes for a MyProjectId project:

/app/rest/changes?locator=project:MyProjectId

To find any changes since a specific change under a build configuration BuildConfigurationID, use:

GET /app/rest/changes?locator=buildType:(id:BuildConfigurationID),sinceChange:(id:changeId)

Finally, to find all pending changes under a build configuration, use:

/app/rest/changes?locator=buildType:(id:BUILD_CONF_ID),pending:true

Get Builds with Specific Revision

To get all builds with a specific revision, use:

/app/rest/builds?locator=revision(version:XXXX)

Get Dependency/Dependent Builds

To get builds which have a snapshot dependency on a given build, use:

/app/rest/builds?locator=snapshotDependency:(to:(id:XXXX),includeInitial:true),defaultFilter:false

To get builds which are a target of snapshot dependency on a given build, use:

/app/rest/builds?locator=snapshotDependency:(from:(id:XXXX),includeInitial:true),defaultFilter:false

To get builds which have an artifact dependency on a given build, use:

/app/rest/builds?locator=artifactDependency:(from:(id:<build ID>),recursive:false)

To get builds which are a target of an artifact dependency on a given build, use:

/app/rest/builds?locator=artifactDependency:(to:(id:<build ID>),recursive:false)

Last modified: 29 March 2022