TeamCity REST API Reference 2025.11 Help

CloudImage

A cloud image that stores settings for individual cloud machine instances (the ID of an instance to start, post-launch sripts, and more). Cloud images are owned by cloud profiles.

Related Help article: Host Build Agents in Cloud

Properties

id

The ID of this cloud image. Typically consists of the truncated image name added to the parent profile ID.

name

The full image name. Includes the public cloud image name and ID.

href

The shortened (without the server URL) link to this cloud image.

profile

The cloud profile that owns this image.

instances

Currently existing virtual machines spawned from this image.

errorMessage

This property is deprecated, use error instead.

error

The CloudError object that stores information about a cloud image problem.

agentTypeId

The value of the typeId property of all agents spawned from this image. Allows you to identify sibling cloud agents.

agentPoolId

The ID of the agent pool to which agents spawned from this image belong.

operatingSystemName

The full name of the OS installed on virtual machines spawned from this image.

webUrl

Returns the full web link to access this cloud image.

locator

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.

<cloudImage 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 cloudProviderId="kube" href="/app/rest/cloud/profiles/id:amazon-4" id="amazon-4" name="AWS EC2 Profile"> <project>[[[project...|project.html]]]</project> <images>[[[cloudImages...|cloudimages.html]]]</images> <error>[[[cloudError...|clouderror.html]]]</error> </profile> <instances count="54" href="/app/rest/cloud/instances" nextHref="/app/rest/cloud/instances?locator=count:200,start:250" prevHref="/app/rest/cloud/instances?locator=count:50,start:0"> <cloudInstance>[[[cloudInstance...|cloudinstance.html]]]</cloudInstance> </instances> <error detailedMessage="Unable to execute HTTP request: ec2.eu-west-1.amazonaws.com" message="Failed to get image info for Ubuntu-22.04-Large"/> </cloudImage>
{ "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" }
Last modified: 02 December 2025