REST API, find first build of specific type for given version


I would like to be able to use the REST API to determine when a build of a certain type has run with a given git commit. At the moment I can use the triggering commit to locate the build but this only works if the build configuration in question is set for to trigger a single build per commit. I would like to be able to disable this setting so that multiple changes can be included in the build and still have a way to locate the first build for a given change.

I'm trying to use the experimental `firstBuilds` method on the REST API and it mostly works.


returns the first build of every configuration that the given git sha is included in. This is ok as I can parse the response and check the `buildTypeId` field to see if the right build has run yet.  

However looking at the API docs it appears that it should be possible to narrow down the returned builds as the changeLocator can have a buildType included as a nested locator. I'm having trouble creating this nested locator

https://host/app/rest/changes/version:<git sha>,buildType:(name:<build type name>)/firstBuilds

The above doesn't narrow down the returned builds at all.

Any help you could provide in constructing the locator would be greatly appreciated.

1 comment

Hello Matthew, 

Not all the methods from our REST API accept the locator. 
The ones that do mention that explicitly in our autodoc, such as the following example:

The latter, for instance, accepts locator parameter (which is a
If you want to fetch the first build on that change on a given configuration, you could do it the other way around, by looking up app/rest/builds with a locator that uses buildType and change dimensions, and finally filtering out the first one.
Here are a couple of examples of such calls:
-Using build type and version:
-Using build type and revision:
Please let me know if you have any more questions.
Thank you,

Please sign in to leave a comment.