BuildLocator

Represents a locator string for filtering Build entities. Examples:

id:1 — find build with ID 1.
buildType:<buildTypeLocator> — find builds under build configuration found by buildTypeLocator.
defaultFilter:false,agent:<agentLocator> — find builds executed on agent found by agentLocator, with defaultFilter disabled (see below).

Properties

Dimension	Data type	Format	Description
`affectedProject`	`string`	`ProjectLocator`	Project (direct or indirect parent) locator.
`agent`	`string`	`AgentLocator`	Agent locator.
`agentTypeId`	`long`	`int64`	typeId of agent used to execute build.
`artifactDependency`	`string`	`GraphDimensions`
`branch`	`string`	`BranchLocator`	Branch locator.
`buildType`	`string`	`BuildTypeLocator`	Build type locator.
`canceled`	`string`		Is canceled. Supported values: `true` `false` `any`
`compatibleAgent`	`string`	`AgentLocator`	Agent locator.
`composite`	`string`		Is composite. Supported values: `true` `false` `any`
`count`	`long`	`int64`	For paginated calls, how many entities to return per page.
`defaultFilter`	`string`		If true, applies default filter 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)). Supported values: `true` `false` `any`
`failedToStart`	`string`		Is failed to start. Supported values: `true` `false` `any`
`finishDate`	`string`	`TimeConditionDimensions`	Requires either date or build dimension.
`hanging`	`string`		Is hanging. Supported values: `true` `false` `any`
`history`	`string`		Is history build. Supported values: `true` `false` `any`
`id`	`long`	`int64`	Build id.
`lookupLimit`	`long`	`int64`	Limit processing to the latest `<lookupLimit>` entities.
`number`	`string`	`ValueConditionDimensions`	Build number string.
`personal`	`string`		Is a personal build. Supported values: `true` `false` `any`
`pinned`	`string`		Is pinned. Supported values: `true` `false` `any`
`project`	`string`	`ProjectLocator`	Project (direct parent) locator.
`property`	`string`	`ParameterConditionDimensions`
`queuedDate`	`string`	`TimeConditionDimensions`	Requires either date or build dimension.
`revision`	`string`	`RevisionDimensions`	Build revision.
`snapshotDependency`	`string`	`GraphDimensions`
`start`	`long`	`int64`	For paginated calls, from which entity to start rendering the page.
`startDate`	`string`	`TimeConditionDimensions`	Requires either date or build dimension.
`state`	`string`		Build state. Supported values: `queued` `running` `finished` `any`
`status`	`string`	`String value`	Status text.
`tag`	`string`	`TagLocator`	Tag locator.
`taskId`	`long`	`int64`	ID of a build or build promotion.
`user`	`string`	`UserLocator`	For personal builds checks the owner of the build, triggering user in other cases.

Last modified: 18 August 2026