CloudInstance
An individual cloud instance spawned from a cloud image.
Related Help article: Host Build Agents in Cloud
Properties
id
The internally used read-only ID of this instance.
name
The name of this instance.
state
A String value that specifies the instance current status. Can return the following values: scheduled to start, scheduled to stop, starting, running, restarting, stopping, stopped, unknown, and error.
startDate
The time of this instance's initial start.
networkAddress
The actual instance address.
href
The relative (without the TeamCity server URL) link to this instance.
image
The CloudImage from which this instance was spawned.
agent
A TeamCity build agent running on this instance.
errorMessage
This property is deprecated, use error instead.
error
A CloudError object that stores information about this instance error.
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.
<cloudInstance errorMessage="string" href="/app/rest/cloud/instances/id:(id:(Windows-Server2022(Instance)),imageId:(Windows-Server2022(Instance)),profileId:amazon-4)" id="id:(Windows-Server2022(Instance)),imageId:(Windows-Server2022(Instance)),profileId:amazon-4" name="i-0245b46070c443201" networkAddress="ec2-54-27-55-38.eu-west-1.compute.amazon.com" startDate="20250515T114320+0200" state="running">
<image agentPoolId="1" agentTypeId="283" errorMessage="string" href="app/rest/cloud/images/id:(id:Win-Server-2022-xLarge,profileId:amazon-1)" id="id:(Ubuntu-22.04-Large(AMI)),profileId:amazon-4" locator="string" name="Win-Server-2022-xLarge (ami-08a0a7588100450ff)" operatingSystemName="Linux, version 5.19.0-1025-aws" webUrl="https://example.com/app/rest/cloudImage/3414">
<profile>[[[cloudProfile...|cloudprofile.html]]]</profile>
<instances>[[[cloudInstances...|cloudinstances.html]]]</instances>
<error>[[[cloudError...|clouderror.html]]]</error>
</image>
<agent authorized="true" connected="true" cpuRank="396" currentAgentVersion="160569" disconnectionComment="Unregistered because of inactivity" enabled="true" host="ip-52-211-39-10.eu-west-1.compute.internal, localhost" href="/app/rest/agents/id:771" id="771" idleSinceTime="20240816T150655+0200" ip="52.211.39.100" javaOutdated="false" lastActivityTime="20240816T151123+0200" locator="string" name="Ubuntu-22.04-Large-i-045902939eae4af1a" outdated="true" pluginsOutdated="false" port="9090" protocol="string" registrationTimestamp="20240816T150655+0200" removed="false" typeId="661" uptodate="false" version="156364" webUrl="https://example.com/agentDetails.html?id=771&agentTypeId=11389&realAgentName=db-win-2003">
<build>[[[build...|build.html]]]</build>
<links>[[[links...|links.html]]]</links>
<enabledInfo>[[[enabledInfo...|enabledinfo.html]]]</enabledInfo>
<authorizedInfo>[[[authorizedInfo...|authorizedinfo.html]]]</authorizedInfo>
<properties>[[[properties...|properties.html]]]</properties>
<cloudInstance>[[[cloudInstance...|]]]</cloudInstance>
<cloudImage>[[[cloudImage...|cloudimage.html]]]</cloudImage>
<environment>[[[environment...|environment.html]]]</environment>
<pool>[[[agentPool...|agentpool.html]]]</pool>
<compatibilityPolicy>[[[compatibilityPolicy...|compatibilitypolicy.html]]]</compatibilityPolicy>
<compatibleBuildTypes>[[[buildTypes...|buildtypes.html]]]</compatibleBuildTypes>
<incompatibleBuildTypes>[[[compatibilities...|compatibilities.html]]]</incompatibleBuildTypes>
<builds>[[[builds...|builds.html]]]</builds>
</agent>
<error detailedMessage="Unable to execute HTTP request: ec2.eu-west-1.amazonaws.com" message="Failed to get image info for Ubuntu-22.04-Large"/>
</cloudInstance>
{
"image" : {
"agentPoolId" : 1,
"instances" : "[[[cloudInstances...|cloudinstances.html]]]",
"agentTypeId" : 283,
"webUrl" : "https://example.com/app/rest/cloudImage/3414",
"profile" : "[[[cloudProfile...|cloudprofile.html]]]",
"name" : "Win-Server-2022-xLarge (ami-08a0a7588100450ff)",
"errorMessage" : "errorMessage",
"id" : "id:(Ubuntu-22.04-Large(AMI)),profileId:amazon-4",
"href" : "app/rest/cloud/images/id:(id:Win-Server-2022-xLarge,profileId:amazon-1)",
"error" : "[[[cloudError...|clouderror.html]]]",
"operatingSystemName" : "Linux, version 5.19.0-1025-aws",
"locator" : "locator"
},
"agent" : {
"disconnectionComment" : "Unregistered because of inactivity",
"idleSinceTime" : "20240816T150655+0200",
"enabledInfo" : "[[[enabledInfo...|enabledinfo.html]]]",
"cpuRank" : 396,
"enabled" : true,
"compatibleBuildTypes" : "[[[buildTypes...|buildtypes.html]]]",
"protocol" : "unidirectional",
"outdated" : true,
"authorized" : true,
"host" : "ip-52-211-39-10.eu-west-1.compute.internal, localhost",
"builds" : "[[[builds...|builds.html]]]",
"links" : "[[[links...|links.html]]]",
"id" : 771,
"href" : "/app/rest/agents/id:771",
"cloudImage" : "[[[cloudImage...|cloudimage.html]]]",
"authorizedInfo" : "[[[authorizedInfo...|authorizedinfo.html]]]",
"incompatibleBuildTypes" : "[[[compatibilities...|compatibilities.html]]]",
"uptodate" : false,
"ip" : "52.211.39.100",
"pool" : "[[[agentPool...|agentpool.html]]]",
"cloudInstance" : "[[[cloudInstance...|]]]",
"version" : "156364",
"connected" : true,
"currentAgentVersion" : "160569",
"compatibilityPolicy" : "[[[compatibilityPolicy...|compatibilitypolicy.html]]]",
"registrationTimestamp" : "20240816T150655+0200",
"environment" : "[[[environment...|environment.html]]]",
"pluginsOutdated" : false,
"removed" : false,
"port" : 9090,
"build" : "[[[build...|build.html]]]",
"webUrl" : "https://example.com/agentDetails.html?id=771&agentTypeId=11389&realAgentName=db-win-2003",
"name" : "Ubuntu-22.04-Large-i-045902939eae4af1a",
"typeId" : 661,
"lastActivityTime" : "20240816T151123+0200",
"locator" : "locator",
"properties" : "[[[properties...|properties.html]]]",
"javaOutdated" : false
},
"name" : "i-0245b46070c443201",
"errorMessage" : "errorMessage",
"id" : "id:(Windows-Server2022(Instance)),imageId:(Windows-Server2022(Instance)),profileId:amazon-4",
"state" : "running",
"href" : "/app/rest/cloud/instances/id:(id:(Windows-Server2022(Instance)),imageId:(Windows-Server2022(Instance)),profileId:amazon-4)",
"error" : {
"detailedMessage" : "Unable to execute HTTP request: ec2.eu-west-1.amazonaws.com",
"message" : "Failed to get image info for Ubuntu-22.04-Large"
},
"networkAddress" : "ec2-54-27-55-38.eu-west-1.compute.amazon.com",
"startDate" : "20250515T114320+0200"
}
Last modified: 02 December 2025