REST API Locators
TeamCity endpoints expose unfiltered lists of related entities. For example, the /app/rest/projects
endpoint returns the complete list of all TeamCity projects that exist on this server. To obtain one specific entity from this list or filter records based on a custom condition, add filter expressions (locators) to your requests.
Locator Dimensions
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:
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.
Explore Available Dimensions
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.
Add Locators to Requests
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, theGET 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, theGET 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.
Default Dimensions
Certain locators have default dimensions. Default dimensions are those whose names you can omit. For example, the following two requests are identical.
Similarly, the following multidimensional locators produce the same results.
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>).
Nested Locators
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.
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.
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):
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:
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:
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.
Pagination
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.
Lookup Limit
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...
...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).
When you reach the default 5000 entities limit, the nextHref
value in the server response automatically adds the lookupLimit
dimension to view other items.
General Recommendations and Best Practices
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
andlookupLimit
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.