TeamCity 2020.2 Help

Manage Builds

This article lists REST API requests concerning builds.

See also an extended use case on how to start and cancel builds.

List builds

GET http://<TeamCity Server host>:<port>/app/rest/builds/?locator=<buildLocator>

Get details of a specific build

GET http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>

Also supports DELETE to delete a build.

Get the list of build configurations in a project with the status of the last finished build in each build configuration

GET http://<TeamCity Server host>:<port>/app/rest/buildTypes?locator=affectedProject:(id:ProjectId)&fields=buildType(id,name,builds($locator(running:false,canceled:false,count:1),build(number,status,statusText)))

Build Locator

Using a locator in build-related requests, you can filter the builds to be returned in the build-related requests. It is referred to as build locator in the scope of REST API.

For some requests, a default filtering is applied which returns only "normal" builds (finished builds which are not canceled, not failed-to-start, not personal, and on default branch (in branched build configurations)), unless those types of builds are specifically requested via the locator. To turn off this default filter and process all builds, add the defaultFilter:false dimension to the build locator. Default filtering varies depending on the specified locator dimensions. For example, when agent or user dimensions are present, personal, canceled, and failed to start builds are included into the results.

Examples of supported build locators:

  • 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.

  • <dimension1>:<value1>,<dimension2>:<value2> — to find builds by multiple criteria.

The list of supported build locator dimensions:

  • project:<project locator> — limit the list to the builds of the specified project (belonging to any build type directly under the project).

  • affectedProject:<project locator> — limit the list to the builds of the specified project (belonging to any build type directly or indirectly under the project)

  • buildType:(<buildTypeLocator>),defaultFilter:false — all the builds of the specified build configuration

  • tag:<tag> — since TeamCity 10, 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. The legacy tags:<tags> locator is supported for compatibility.

  • status:<SUCCESS/FAILURE/UNKNOWN> — list builds with the specified status only.

  • user:(<userLocator>) — limit builds to only those triggered by the user specified.

  • 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 (since TeamCity 10.0 ).

  • pinned:<true/false/any> — limit builds by the pinned flag.

  • branch:<branch locator> — limit the builds by branch. <branch locator> 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 path will look like this: /app/rest/builds/?locator=buildType:One_Git,branch:default:any.

  • revision:<REVISION> — find builds by revision, for example all builds of the given build configuration with the revision: /app/rest/builds?locator=revision:(REVISION),buildType:(id:BUILD_TYPE_ID). See more information below.

  • 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

  • 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 build locator, for example for the builds finished after November 23, 2017, 20:34:46, GMT+1 timezone use: 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.

Queued Builds

Get a build queue

GET http://<TeamCity Server host>:<port>/app/rest/buildQueue

Supported locators:

  • project:<locator>
  • buildType:<locator>

Get details of a queued build

GET http://<TeamCity Server host>:<port>/app/rest/buildQueue/id:XXX

For queued builds with snapshot dependencies, the revisions are available in the revisions element of the queued build node if a revision is fixed (for regular builds without snapshot dependencies it is not).

Get compatible agents for queued builds (useful for builds having "No agents" to run on)

GET http://<TeamCity Server host>:<port>/app/rest/buildQueue/id:XXX/compatibleAgents

Examples:

List queued builds per project

GET http://<TeamCity Server host>:<port>/app/rest/buildQueue?locator=project:<locator>

List queued builds per build configuration

GET http://<TeamCity Server host>:<port>/app/rest/buildQueue?locator=buildType:<locator>

Triggering Build

To start a build, send a POST request to http://<TeamCity Server host>:<port>/app/rest/buildQueue with the "build" node (see below) in content — the same node as details of a queued build or finished build. The queued build details will be returned.

When the build is started, the request to the queued build (/app/rest/buildQueue/XXX) will return running/finished build data. This way, you can monitor the build completeness by querying build details using the href attribute of the build details returned on build triggering, until the build has the state="finished" attribute.

Build node example

Basic build for a build configuration:

<build> <buildType id="buildConfID"/> </build>

Build for a branch marked as personal with a fixed agent, comment and a custom parameter:

<build personal="true" branchName="logicBuildBranch"> <buildType id="buildConfID"/> <agent id="3"/> <comment><text>build triggering comment</text></comment> <properties> <property name="env.myEnv" value="bbb"/> </properties> </build>

Queued build assignment to an agent pool:

<build>... <agent> <pool id="N"/> </agent> ... </build>

Build on a change of given revision, forced rebuild of all dependencies and clean sources before the build, moved to the build queue top on triggering. (Note that the change should be already known to TeamCity (displayed in UI for the build configuration, more on the "lastChanges" element ):

<build> <triggeringOptions cleanSources="true" rebuildAllDependencies="true" queueAtTop="true"/> <buildType id="buildConfID"/> <lastChanges> <change locator="version:a286767fc1154b0c2b93d5728dd5bbcdefdfaca,buildType:(id:buildConfID)"/> </lastChanges> </build>

Example command line for the build triggering:

curl -v -u user:password http://<TeamCity Server host>:<port>/app/rest/buildQueue --request POST --header "Content-Type:application/xml" --data-binary @build.xml

Build Tags

Get tags

GET http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/tags/

Replace tags

PUT http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/tags/

Put the same XML or JSON as returned by GET.

Add tags

POST http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/tags/

Post the same XML or JSON as returned by GET or just a plain-text tag name; <buildLocator> here should match a single build only.

Example of XML for two tags:

<tags> <tag name="<tag1>"/> <tag name="<tag2>"/> </tags>

Build Pinning

Get current pin status

GET http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/pin/

Pin a build

PUT http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/pin/

The text in the request data is added as a comment for the action.

Unpin a build

DELETE http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/pin/

The text in the request data is added as a comment for the action; <buildLocator> here should match a single build only.

Build Canceling/Stopping

Cancel a queued build

POST the <buildCancelRequest comment='CommentText' readdIntoQueue='false'/> item to the URL of a queued build. Example:

curl -v -u user:password --request POST "http://<TeamCity Server host>:<port>/app/rest/buildQueue/<buildLocator>" --data "<buildCancelRequest comment='' readdIntoQueue='false' />" --header "Content-Type: application/xml"

Stop a running build and readd it to the queue

POST the <buildCancelRequest comment='CommentText' readdIntoQueue='true' /> item to the URL of a running build. Example:

curl -v -u user:password --request POST "http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>" --data "<buildCancelRequest comment='' readdIntoQueue='true' />" --header "Content-Type: application/xml"

Set readdIntoQueue to false to stop the build without readding it to the queue.

See the canceledInfo element of the build item

Available via GET http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>.

Build Artifacts

Return the content of a build artifact file for a build determined by <build_locator>

GET http://<TeamCity Server host>:<port>/app/rest/builds/<build_locator>/artifacts/content/<path>

<path> can be empty for the root of build's artifacts or be a path within the build's artifacts. The path can span into the archive content, for example, dir/path/archive.zip!/path_within_archive.

  • Media-Type: application/octet-stream or a more specific media type (determined from artifact file extension).

  • Possible error: 400 if the specified path references a directory.

Return information about a build artifact

GET http://<TeamCity Server host>:<port>/app/rest/builds/<build_locator>/artifacts/metadata/<path>

  • Media-Type: application/xml or application/json.

Return the list of artifact children for directories and archives

GET http://<TeamCity Server host>:<port>/app/rest/builds/<build_locator>/artifacts/children/<path>

  • Media-Type: application/xml or application/json.

  • Possible error: 400 if the artifact is neither a directory nor an archive.

Return an archive containing the list of artifacts under the path specified

GET http://<TeamCity Server host>:<port>/app/rest/builds/<build_locator>/artifacts/archived/<path>?locator=pattern:<wildcard>

The optional locator parameter can have file <wildcard> to limit the files only to those matching the wildcard. <artifact relative name> supports referencing files under archives using the !/ delimiter after the archive name.

  • Media-Type: application/zip.

  • Possible error: 400 if the artifact is neither a directory nor an archive.

Examples:

GET http://<TeamCity Server host>:<port>/app/rest/builds/id:100/artifacts/children/my-great-tool-0.1.jar!/META-INF GET http://<TeamCity Server host>:<port>/app/rest/builds/buildType:(id:Build_Intallers),status:SUCCESS/artifacts/metadata/my-great-tool-0.1.jar!/META-INF/MANIFEST.MF GET http://<TeamCity Server host>:<port>/app/rest/builds/buildType:(id:Build_Intallers),number:16.7.0.2/artifacts/metadata/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF GET http://<TeamCity Server host>:<port>/app/rest/builds/buildType:(id:Build_Intallers),tag:release/artifacts/content/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF

Authentication

If you download artifacts from within a TeamCity build, consider using values of teamcity.auth.userId/teamcity.auth.password system properties as credentials for the download artifacts request: this way TeamCity will have a way to record that one build used artifacts of another and will display it on the build's Dependencies tab.

Other Build Requests

Changes

<changes> is meant to represent changes the same way as displayed in the build's Changes in TeamCity UI. In the most cases these are the commits between the current and previous build. The <changes> tag is not included into the build by default, it has the href attribute only. If you execute the request specified in href, you'll get the required changes.

Get the list of all changes included into the build

GET http://<TeamCity Server host>:<port>/app/rest/changes?locator=build:(id:<buildId>)

Get details of an individual change

GET http://<TeamCity Server host>:<port>/app/rest/changes/id:changeId

Get information about a changed file action

The file's node lists changed files. The information about the changed file action is reported via the changeType attribute for the files listed as added, edited, removed, copied, or unchanged.

Filter all changes by a locator

GET http://<TeamCity Server host>:<port>/app/rest/changes?locator=<changeLocator>

Get all changes for a project

GET http://<TeamCity Server host>:<port>/app/rest/changes?locator=project:projectId

Get all the changes in a build configuration since a particular change identified by its ID

http://<TeamCity Server host>:<port>/app/rest/changes?locator=buildType:(id:buildConfigurationId),sinceChange:(id:changeId)

Get pending changes for a build configuration

http://<TeamCity Server host>:<port>/app/rest/changes?locator=buildType:(id:BUILD_CONF_ID),pending:true

The <lastChanges> tag contains information about the last commit included into the build. When triggering a build, its nested <change> element can contain the locator field that specifies what change to use for the build triggering.

Revisions

The <revisions> tag the same as revisions table on the build's Changes tab in TeamCity UI: it lists the revisions of all VCS repositories associated with this build that will be checked out by the build on the agent. A revision might or might not correspond to a change known to TeamCity. For example, for a newly created build configuration and a VCS root, a revision will have no corresponding change.

Get all builds with the specified revision

GET http://<TeamCity Server host>:<port>/app/rest/builds?locator=revision(version:XXXX)

Since TeamCity 10, <versionedSettingsRevision> is added to represent revision of the versioned settings of the build.

Snapshot dependencies

Find all the snapshot dependency builds in the build chain upstream for the build with the ID XXXX.

GET http://<TeamCity Server host>:<port>/app/rest/builds?locator=snapshotDependency:(to:(id:XXXX),includeInitial:true),defaultFilter:false

Find all the snapshot-dependent builds in all build chains downstream for the build with the ID XXXX.

GET http://<TeamCity Server host>:<port>/app/rest/builds?locator=snapshotDependency:(from:(id:XXXX),includeInitial:true),defaultFilter:false

Artifact dependencies

Since TeamCity 10.0.3, there is an experimental ability to:

Get all the builds which downloaded artifacts from the build with the given ID (Delivered artifacts in the TeamCity web UI)

GET http://<TeamCity Server host>:<port>/app/rest/builds?locator=artifactDependency:(from:(id:<build ID>),recursive:false)

Get all the builds whose artifacts were downloaded by the build with the given ID (Downloaded artifacts in the TeamCity web UI)

GET http://<TeamCity Server host>:<port>/app/rest/builds?locator=artifactDependency:(to:(id:<build ID>),recursive:false)

VCS Labels

Get VCS labels of a build

by adding the vcsLabels field:

GET http://<TeamCity Server host>:<port>/app/rest/builds?locator=<buildLocator>&fields=build(id,vcsLabels:$long)

or via a separate request:

GET http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/vcsLabels?fields=status,text

Add a VCS label to a build

POST http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/vcsLabels?locator=<vcsRootInstanceLocator>&fields=build(id,vcsLabels)

where locator is optional and specifies where to put labels; if not specified, a label will be added to all instances of a VCS root.

Build Parameters

Get the parameters of a build

GET http://<TeamCity Server host>:<port>/app/rest/builds/id:<build_id>/resulting-properties

Build Fields

Get a single build's field

GET http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/<field_name>

This accepts/produces text/plain where <field_name> is one of number, status, id, branchName, and other build's bean attributes.

Statistics

See also detailed uses cases on how to get the build statistics.

Get statistics for a single build

GET http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/statistics/

Only standard/bundled statistic values are listed. See also Custom Charts.

Get single build statistics value

GET http://<TeamCity Server host>:<port>/app/rest/builds/<buildLocator>/statistics/<value_name>

Get statistics for a list of builds

GET http://<TeamCity Server host>:<port>/app/rest/builds?locator=BUILDS_LOCATOR&fields=build(id,number,status,buildType(id,name,projectName),statistics(property(name,value)))

Build Log

Downloading build logs via a REST request is not supported, but there is a way to download the log files described here.

Last modified: 20 February 2021
Manage Typed Parameters Start and Cancel Builds