REST API Locators

A dimension is a single criterion that you can use to construct a final filter expression (locator). To specify a condition, use the dimension:value syntax. A locator can include multiple comma-separated conditions:

dimension1:value1,dimension2:value2,dimension3:value3

Some dimensions accept values of regular types (string, integer, Boolean, and so on). For example, the BuildLocator allows you to define the status:failure and failedToStart:true conditions.

Other dimensions accept locators as values. See the Nested Locators section to learn more.

Different endpoints have different sets of available locator dimensions. Add $help to your request to reveal the dimensions available for this endpoint. For example, the following Postman screenshot illustrates the response to the GET https://<server-url>/app/rest/builds/$help request.

note

Some dimensions revealed via the $help locator can be obsolete and not recommended to be used. Check the related locator in this documentation's "Autogenerated REST API Reference | Locators" section to ensure the dimension you intend to use is public. For example, the following page lists all public dimensions for the app/rest/builds endpoint: BuildLocator.

To add a locator to a request, use either the path (/locator) or query (?locator=) parameter syntax.

• Use /locator to obtain the first (topmost) result that satisfies the given condition. For example, the GET https://<server-url>/app/rest/projects/name:Build request returns the first found project whose public name is "Build".

  

• Use ?locator= to obtain the list of all objects that fit the given criteria. For example, the GET https://<server-url>/app/rest/projects?locator=name:Build request returns all projects whose public names are "Build". Nte that in the image below the first build of a list is the same build returned by the /app/rest/projects/name:Build request.

  

Certain locators have default dimensions. Default dimensions are those whose names you can omit. For example, the following two requests are identical.

/app/rest/builds/id:284395922
/app/rest/builds/284395922

Similarly, the following multidimensional locators produce the same results.

?locator=buildType:TC_Trunk_Compile,startDate:(build:281819048,condition:after)
?locator=buildType:id:TC_Trunk_Compile,startDate:(build:id:281819048,condition:after)

Most locators' default dimension is the ID, internal ID, or name.

In this shortened syntax, values should include only alphanumeric characters with no symbols like ,, :, -, (, ). If a value contains the comma character (,), enclose this value in parentheses: (<value>).

note

Dimension values can be encoded as Base64url ("URL and Filename safe type base64" from RFC4648). To do this, use the dimensionName:($base64:<base64-encoded-value>) syntax.

tip

We recommend using the shortened "nameless" syntax only for most basic and straightforward requests. The full syntax that explicitly specifies all dimension names improves request readability and is easier to maintain.

Certain dimensions accept locators as values. In the request below, the BuildLocator uses a nested BuildTypeLocator to find builds for the "TC_Trunk_Compile" build configuration.

GET
/app/rest/builds?locator=buildType:TC_Trunk_Compile,startDate:(date:20200101T000000%2B0100,condition:after),status:failure

In this sample request, the startDate dimension filters out builds run before the threshold date. The startDate dimension can also accept BuildLocators instead of specific DateTime values. Use this option to search for builds run before or after the particular build.

GET
/app/rest/builds?locator=buildType:TC_Trunk_Compile,startDate:(build:281819048,condition:after),status:failure

This request uses nested BuildTypeLocator and BuildLocator without dimension names, so entities are filtered by their IDs (see the Default Dimensions section). In other words, the request above is similar to the following (nested locators are enclosed in parentheses for better readability):

GET
/app/rest/builds?locator=buildType:(id:TC_Trunk_Compile),startDate:(build:(id:281819048),condition:after),status:failure

Let's try to use non-default dimensions instead. For example, the public build number of the "id:281819048" build is "88977".

Modify the request as follows to set a threshold build by this build number:

GET
/app/rest/builds?locator=buildType:TC_Trunk_Compile,startDate:(build:(number:88977),condition:after),status:failure

This request will likely fail (return "404: Not Found") since build numbers are unique only within their parent build configuration scope. In the server scope, build numbers are repeated (each build configuration has build #1, build #2, and so on). As a result, the nested BuildLocator can retrieve the "88977" build that belongs to a different configuration, which in turn will cause a mismatch with the previous buildType:TC_Trunk_Compile condition.

To fix this issue, you need to point the nested BuildLocator to the same build configuration as in the parent locator:

GET
/app/rest/builds?locator=buildType:TC_Trunk_Compile,startDate:(build:(buildType:TC_Trunk_Compile,number:88977),condition:after),status:failure`

While this last request is valid and functional, we recommend sticking to ID dimensions. Locators based on unique IDs are less prone to errors and generally make the most effective filters.

Requests that cause TeamCity to process large lists can lead to timeouts and performance issues. To prevent this, TeamCity breaks down such lists into batches (pages), each containing 100 entities. A server sends a response when a batch of 100 records is ready.

Entities are returned in collections that contain the following information related to pagination:

• count — The number of entities in this batch.

• start — The zero-based index of this batch's first record. This index reflects the record's position within the entire list of found entities.

• nextHref — The locator that allows you to view the next page.

• prevHref — The locator that allows you to view the previous page.

You can send requests with custom count and start values. For example, the following request finds all builds of the "TC_Trunk" project and returns the list of 200 builds starting with the 50th record.

GET
/app/rest/builds?locator=project:TC_Trunk,count:200,start:50

TeamCity REST API sets an internal limit of 5000 entities processed on each request. For example, if your build server has over 5000 builds and you send the following request...

GET
/app/rest/builds?locator=start:4999

...the response will contain just one build. If your start equals 5000 or higher, TeamCity returns a list with zero items.

You can add the lookupLimit:<value> condition to your requests to override this default 5000 entities limit. The following request forces TeamCity to process the first 7000 builds and returns builds #6000 to #6100 (the default count value is 100).

GET
/app/rest/builds?locator=start:6000,lookupLimit:7000

When you reach the default 5000 entities limit, the nextHref value in the server response automatically adds the lookupLimit dimension to view other items.

• Specify dimensions to narrow the search and thus avoid exhaustive searches and reduce the server load. For example, when looking for builds of the specific build configuration, specify the buildType dimension.

• Be aware of the count and lookupLimit dimensions. Your search results can be incomplete because of these built-in limits (5000 scanned entities and 100 entities per response by default).

• When looking for builds, TeamCity processes only builds for the default branch. Add the branch:<any> dimension to process all builds instead.

• If your requests fail or take too long to process, you can inspect the TeamCity REST log for potential clues. To enable this log, go to Administration | Diagnostics | Troubleshooting and set the Active logging preset to "debug-rest". The log file is available in the Administration | Diagnostics | Server Logs tab.