You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.


Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


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.
By default, only finished, not canceled, not failedToStart not personal builds from default branch are returned. TO return all build, use "defaultFilter:false" dimension.

Examples of supported build locators:


The list of supported build locator dimensions:
buildType:(<buildTypeLocator>) - only the builds of the specified build configuration
tags:<tags> - ","(comma) - a delimited list of build tags (only builds containing all the specified tags are returned)
status:<SUCCESS/FAILURE/ERROR> - 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, perfsonal 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   (since TeamCity 9.1) limit builds by the failed to start flag (since TeamCity 9.1). By default, canceled builds are not included.
running:<true/false/any> - limit builds by the running flag. By default, running builds are not included.
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>)".  Note: If a build configuration utilizes feature branches, by  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: /httpAuth/app/rest/builds/?locator=buildType:One_Git,branch:default:any
agentName:<name> - agent name to return only builds ran on the agent with name specified
sinceBuild:(<buildLocator>) - limit the list of builds only to those after the one specified
sinceDate:<date><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 (e.g. "20130305T170030+0400").
project:<project locator>locator> - limit the list to the builds of the specified project (belonging to any build type directly under the project).Before  Before TeamCity 9.1 this 1 this traversed projects recursively: with meaning "belonging to any build type directly or indirectly under the project".
affectedProject:<project locator>locator> - - (since TeamCity 9.1) limit  limit the list to the builds of the specified project (belonging to any build type directly or indirectly under the project) 
count:<number><number> - serve only the specified number of builds
start:<number><number> - list the builds from the list starting from the position specified (zero-based)
lookupLimit:<number><number> - limit processing to the latest N builds only. If none of the latest N builds match the other specified criteria of the build locator, 404 response is returned. 


Queued Builds

GET http://teamcity:8111/httpAuth/app/rest/buildQueue


Basic build for a build configuration:

Code Block
    <buildType id="buildConfID"/>