Build
A process that performs a certain CI/CD job. Most builds comprise multiple sequential steps executing their own granular actions. A build is executed according to the settings specified in its build configuration (BuildType). See the Manage Builds section for the examples on various build actions.
Properties
id
The automatically generated unique ID of the build.
taskId
buildTypeId
Returns the ID of the corresponding build configuration. To obtain this configuration itself, use the buildType property instead.
buildTypeInternalId
This property supports the internal infrastructure and is not intented to be used. Use the buildTypeId property instead to access the regular build configuration ID.
number
Returns a public build number this build is assigned in its build configuration, null if a build is still queued, or N/A if a queued build was canceled before it started.
status
Returns whether a build has finished successfully (or is expected to finish so, if still running). Possible values:
null for queued builds.
SUCCESS for builds that have successfully finished or still running without errors.
FAILURE for builds that failed to start or failed during their run.
UNKNOWN for canceled builds.
state
Returns the actual stage of the build's lifecycle: queued, running, or finished.
running
Returns true if the build is currently running; otherwise, false.
composite
Returns true if this is build is composite; otherwise, false.Composite builds aggregate results of multiple child builds. These builds can belong to composite build configurations or can be spawned automatically (for example, to aggregate results of parallel tests).
failedToStart
Returns true if this build was automatically removed from the building queue (for example, if an error occured or the appointed reviewers failed to approve the build in time); otherwise, false.Does not return true for manually cancelled builds
personal
Returns true for personal builds and false for regular builds.
percentageComplete
This property is deprecated, see running-info property instead.
branchName
Returns the name of the repository branch whose changes are processed in the current build. This property returns the logical branch name (main), not a fully specified VCS branch name (refs/heads/main).
defaultBranch
Returns true if the current build processes changes from the branch specified as default branch in VCS root settings; otherwise, false.
unspecifiedBranch
Returns true if the branch name equals <unspecified> otherwise, false. A branch can have this name if TeamCity fails to retrieve a valid branch name.
history
Returns true for history builds that started after a build with most recent code changes; otherwise, false.
pinned
Returns true if the build is currently pinned; otherwise, false.Send GET and PUT requests to /app/rest/builds/<build-locator>/pinInfo to get the detailed information about pinned builds and manually pin/unpin these builds.
href
Returns the shortened (without the server URL) link to the current build. To obtain the full URL, use the webUrl property instead.
webUrl
Returns the full web link to access this build. To get a link without the server URL, read the href property instead.
queuePosition
Returns the build's position in the building queue.
limitedChangesCount
Returns the number of changes processed in this build.
artifactsDirectory
Returns the path to the built-in artifact storage.
links
Returns the collection of links to this build.
statusText
Returns the additional information about the finished or running build. Returns nothing if a build is still queued, read the waitReason property instead to get the current status of a queued build.In TeamCity UI, this string is displayed next to the build status icon ("Canceled", "Step 3/7", "Error while applying patch", and so on).
buildType
Returns the build configuration to which the current build belongs.
comment
Returns the comment for this build, and the user who wrote it.
tags
Returns the collection of tags that decorate this build.
pinInfo
Allows you to identify who and when pinned this build. Returns null for builds whose pinned is false.
user
Returns the user associated with this personal build, or null of this build is not personal.
startEstimate
If this build is still queued, this property returns the estimated time (UTC) of an actual build start.
waitReason
Returns the actual reason why this build remains in build queue. This property returns the most recent wait reason from the queuedWaitReasons array.
finishEstimate
Returns the estimated time this build will finish. Returns a value only for queued builds and null for those that already run.
delayedByBuild
Returns the build that must finish before the currently queued build can start.
plannedAgent
Returns the agent that TeamCity currently expects to assign to this queued build. Use compatibleAgents instead to obtain the list of all agents that can run this build.
approvalInfo
Allows you to identify who and when allowed this build to start. This information is written if a build configuration has the Build Approval feature configured and/or the project Untrusted Builds settings filter out potentially harmful builds.
running-info
Returns the RunningBuildInfo object that stores data related to the build completion stage: completion percentage, elapsed and remaining time, build health (hanging or running as expected), and so on.Returns null for queued and finished builds.
canceledInfo
Allows you to retrieve detailed information about this canceled build: a user who canceled it, their comment, and the cancel timestamp. Returns null for non-canceled builds.
queuedDate
Returns the date and time (UTC) when this build was queued. Note that the moment this build actually starts is stored in the different property (startDate)..
startDate
Returns the date and time (UTC) of the moment the build actually started. Note that the moment a build was triggered is stored in the queuedDate property.
finishDate
Returns the date and time of the moment the build was removed from the queue (finished, failed, or was canceled). The value is in UTC and corresponds to the server timezone.
triggered
Allows you to identify the time this build was triggered, and the authority that ussued the build command (user, vcs trigger, schedule trigger, and so on).
lastChanges
Returns the topmost element of the changes collection. Corresponds to the latest change processed in this build.
changes
Returns the list of changes processed in this build. Use limitedChangesCount to obtain the number of these changes, or lastChanges to get the latest one.
revisions
Returns the list of revisions associated with this build.
versionedSettingsRevision
Returns the revision of build configuration settings stored in a VCS.
artifactDependencyChanges
agent
Returns a build agent that processed (or currently processes) this build.If the build has not yet started and awaits in the build queue, this property returns null. In this case you can check the plannedAgent property to obtain the agent that will likely run the build.
compatibleAgents
If a build is still in building queue, this property returns the list of all agents that can run it. Use plannedAgent to obtain an agent from this list that TeamCity expects to assign to this build.
compatibleCloudImages
Returns all cloud images that can spawn agents compatible with this build.
testOccurrences
Returns the TestOccurences object that stores information on test instances run in this build.
problemOccurrences
Returns the list of build problems that led to the build failure.
artifacts
Returns the list of public build artifacts. See this section for the examples of downloading specific files: Get Build Artifacts.
relatedIssues
Returns the list of issues associated with changes processed in this build.
properties
Returns the collection of custom build properties (including those added by users in the Run Custom Build dialog) and their current values.
resultingProperties
Returns the complete list of predefined and custom properties with their final values. Final values are those reported by a build agent after a build finishes. These include values changed during a build and via the Run Custom Build dialog.
originalProperties
Returns the collection of user-defined properties and their original values. Original values are those stored in the build configuration and assigned to any new build that runs with default settings.
startProperties
Returns the complete list of predefined and custom properties with their starting values. Starting values are those reported by a build agent when a build actually starts. These are a combination of original values (see originalProperties) for properties that were not modified, and custom values for properties edited via the Run Custom Build dialog.
attributes
Returns the list of Entries owned by this build.
statistics
Returns the list of statistical metrics for the current build (ArtifactsSize, BuildDuration, SuccessRate, TimeSpentInQueue, and so on).
metadata
Returns the metadata associated with this build.
snapshot-dependencies
Returns all upstream builds on which the current build depends. In the BuildA → BuildB → BuildC chain, this property returns:
empty array for BuildA;
array with BuildA for BuildB;
array with BuildA and BuildB for BuildC.
artifact-dependencies
Returns all upstream builds whose artifacts were exported to this build.
custom-artifact-dependencies
Allows you to override artifact dependencies specified in Build Configuration settings and specify custom dependencies for this specific build. See this section for the sample payload: Manage Dependencies.
settingsHash
currentSettingsHash
modificationId
chainModificationId
replacementIds
related
triggeringOptions
Allows you to define custom triggering options (for example, whether the build should get the top spot in the build queue or force clean its sources).
usedByOtherBuilds
Returns true if at least one dependent build has reused this build instead of triggering a new one.
statusChangeComment
Returns the Comment object that stores information about user who changed the status of this build, and their notes regarding this change.This property may be deprecated in future API versions, use ...Info properties (approvalInfo, canceledInfo, and so on) instead.
vcsLabels
Returns a list of labels that tag sources of this particular build.
detachedFromAgent
Returns true, if running build no longer occupies a build agent; otherwise, false.
finishOnAgentDate
Similar to the finishDate property, but adjusts the date and time according to the agent timezone.
customized
Returns true if the build is running with non-default parameter, dependency, and (or) changes settings (for example, reuses the manually selected build or targets the specific changes revision instead of building latest changes); otherwise, false.
customization
Returns the list of settings that differentiate this build from a default build of the same build configuration.
changesCollectingInProgress
Returns true if the build is currently collecting changes from a remote repository; otherwise, false.
queuedWaitReasons
Returns all reasons why this build remains queued. Use waitReason to obtain the primary reason displayed in TeamCity UI.
downloadedArtifacts
Returns the collection metadata objects associated with artifacts that were downloaded from dependencies of this build, or exported to builds dependent of the current one.
matrixConfiguration
Specifies whether this build belongs to a Matrix builds configuration.
firstBuildWithSameChanges
For history builds (builds whose history property is true), returns the most recent finished build that processed the same revision of the source code.
locator
See REST API Locators for more information.
Schema
Below, you can find a full schema of this object, in XML and JSON formats. You can choose what fields to submit depending on your current needs. Different methods might expect different fields: the best approach is to request this entity via GET and use the response as a base for the following POST request.
A link to another object implies that you can substitute it with the schema of the linked object, if it is required for your call.