# REST Resource: projects.locations.queuedResources

- [Resource: QueuedResource](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#QueuedResource)
  - [JSON representation](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#QueuedResource.SCHEMA_REPRESENTATION)
- [Tpu](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#Tpu)
  - [JSON representation](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#Tpu.SCHEMA_REPRESENTATION)
- [NodeSpec](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#NodeSpec)
  - [JSON representation](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#NodeSpec.SCHEMA_REPRESENTATION)
- [MultisliceParams](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#MultisliceParams)
  - [JSON representation](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#MultisliceParams.SCHEMA_REPRESENTATION)
- [Spot](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#Spot)
- [Guaranteed](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#Guaranteed)
  - [JSON representation](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#Guaranteed.SCHEMA_REPRESENTATION)
- [QueueingPolicy](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#QueueingPolicy)
  - [JSON representation](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#QueueingPolicy.SCHEMA_REPRESENTATION)
- [QueuedResourceState](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#QueuedResourceState)
  - [JSON representation](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#QueuedResourceState.SCHEMA_REPRESENTATION)
- [State](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#State)
- [CreatingData](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#CreatingData)
- [AcceptedData](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#AcceptedData)
- [ProvisioningData](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#ProvisioningData)
- [FailedData](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#FailedData)
  - [JSON representation](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#FailedData.SCHEMA_REPRESENTATION)
- [DeletingData](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#DeletingData)
- [ActiveData](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#ActiveData)
- [SuspendingData](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#SuspendingData)
- [SuspendedData](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#SuspendedData)
- [StateInitiator](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#StateInitiator)
- [Methods](https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#METHODS_SUMMARY)

## Resource: QueuedResource

A QueuedResource represents a request for resources that will be placed in a queue and fulfilled when the necessary resources are available.

| JSON representation |
|---|
| ``` { "name": string, "createTime": string, "queueingPolicy": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#QueueingPolicy`) }, "state": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#QueuedResourceState`) }, "reservationName": string, // Union field `resource` can be only one of the following: "tpu": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#Tpu`) } // End of list of possible types for union field `resource`. // Union field `tier` can be only one of the following: "spot": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#Spot`) }, "guaranteed": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#Guaranteed`) } // End of list of possible types for union field `tier`. } ``` |

| Fields ||
|---|---|
| `name` | `string` Output only. Immutable. The name of the QueuedResource. |
| `createTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. The time when the QueuedResource was created. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `queueingPolicy` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#QueueingPolicy`)`` Optional. The queueing policy of the QueuedRequest. |
| `state` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#QueuedResourceState`)`` Output only. State of the QueuedResource request. |
| `reservationName` | `string` Optional. Name of the reservation in which the resource should be provisioned. Format: projects/{project}/locations/{zone}/reservations/{reservation} |
| Union field `resource`. Resource specification. `resource` can be only one of the following: ||
| `tpu` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#Tpu`)`` Optional. Defines a TPU resource. |
| Union field `tier`. Tier specifies the required tier. `tier` can be only one of the following: ||
| `spot` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#Spot`)`` Optional. The Spot tier. |
| `guaranteed` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#Guaranteed`)`` Optional. The Guaranteed tier |

## Tpu

Details of the TPU resource(s) being requested.

| JSON representation |
|---|
| ``` { "nodeSpec": [ { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#NodeSpec`) } ] } ``` |

| Fields ||
|---|---|
| `nodeSpec[]` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#NodeSpec`)`` Optional. The TPU node(s) being requested. |

## NodeSpec

Details of the TPU node(s) being requested. Users can request either a single node or multiple nodes. NodeSpec provides the specification for node(s) to be created.

| JSON representation |
|---|
| ``` { "parent": string, "node": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.nodes#Node`) }, // Union field `name_strategy` can be only one of the following: "nodeId": string, "multisliceParams": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#MultisliceParams`) } // End of list of possible types for union field `name_strategy`. } ``` |

| Fields ||
|---|---|
| `parent` | `string` Required. The parent resource name. |
| `node` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.nodes#Node`)`` Required. The node. |
| Union field `name_strategy`. Either a node_id or multislice_params. `name_strategy` can be only one of the following: ||
| `nodeId` | `string` Optional. The unqualified resource name. Should follow the `^[A-Za-z0-9_.~+%-]+$` regex format. This is only specified when requesting a single node. In case of multislice requests, multisliceParams must be populated instead. |
| `multisliceParams` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#MultisliceParams`)`` Optional. Fields to specify in case of multislice request. |

## MultisliceParams

Parameters to specify for multislice QueuedResource requests. This message must be populated in case of multislice requests instead of nodeId.

| JSON representation |
|---|
| ``` { "nodeCount": integer, "nodeIdPrefix": string } ``` |

| Fields ||
|---|---|
| `nodeCount` | `integer` Required. Number of nodes with this spec. The system will attempt to provision "nodeCount" nodes as part of the request. This needs to be \> 1. |
| `nodeIdPrefix` | `string` Optional. Prefix of node_ids in case of multislice request. Should follow the `^[A-Za-z0-9_.~+%-]+$` regex format. If nodeCount = 3 and nodeIdPrefix = "np", node ids of nodes created will be "np-0", "np-1", "np-2". If this field is not provided we use queuedResourceId as the nodeIdPrefix. |

## Spot

This type has no fields.
Spot tier definition.

## Guaranteed

Guaranteed tier definition.

| JSON representation |
|---|
| ``` { "minDuration": string } ``` |

| Fields ||
|---|---|
| `minDuration` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` Optional. Defines the minimum duration of the guarantee. If specified, the requested resources will only be provisioned if they can be allocated for at least the given duration. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |

## QueueingPolicy

Defines the policy of the QueuedRequest.

| JSON representation |
|---|
| ``` { // Union field `start_timing_constraints` can be only one of the following: "validUntilDuration": string, "validUntilTime": string, "validAfterDuration": string, "validAfterTime": string, "validInterval": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/Shared.Types/Interval`) } // End of list of possible types for union field `start_timing_constraints`. } ``` |

| Fields ||
|---|---|
| Union field `start_timing_constraints`. Time flexibility specification. `start_timing_constraints` can be only one of the following: ||
| `validUntilDuration` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` Optional. A relative time after which resources should not be created. If the request cannot be fulfilled by this time the request will be failed. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |
| `validUntilTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Optional. An absolute time after which resources should not be created. If the request cannot be fulfilled by this time the request will be failed. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `validAfterDuration` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` Optional. A relative time after which resources may be created. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |
| `validAfterTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Optional. An absolute time after which resources may be created. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `validInterval` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/Shared.Types/Interval`)`` Optional. An absolute time interval within which resources may be created. |

## QueuedResourceState

QueuedResourceState defines the details of the QueuedResource request.

| JSON representation |
|---|
| ``` { "state": enum (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#State`), "stateInitiator": enum (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#StateInitiator`), // Union field `state_data` can be only one of the following: "creatingData": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#CreatingData`) }, "acceptedData": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#AcceptedData`) }, "provisioningData": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#ProvisioningData`) }, "failedData": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#FailedData`) }, "deletingData": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#DeletingData`) }, "activeData": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#ActiveData`) }, "suspendingData": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#SuspendingData`) }, "suspendedData": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#SuspendedData`) } // End of list of possible types for union field `state_data`. } ``` |

| Fields ||
|---|---|
| `state` | ``enum (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#State`)`` Output only. State of the QueuedResource request. |
| `stateInitiator` | ``enum (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#StateInitiator`)`` Output only. The initiator of the QueuedResources's current state. Used to indicate whether the SUSPENDING/SUSPENDED state was initiated by the user or the service. |
| Union field `state_data`. Further data for the state. `state_data` can be only one of the following: ||
| `creatingData` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#CreatingData`)`` Output only. Further data for the creating state. |
| `acceptedData` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#AcceptedData`)`` Output only. Further data for the accepted state. |
| `provisioningData` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#ProvisioningData`)`` Output only. Further data for the provisioning state. |
| `failedData` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#FailedData`)`` Output only. Further data for the failed state. |
| `deletingData` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#DeletingData`)`` Output only. Further data for the deleting state. |
| `activeData` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#ActiveData`)`` Output only. Further data for the active state. |
| `suspendingData` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#SuspendingData`)`` Output only. Further data for the suspending state. |
| `suspendedData` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources#SuspendedData`)`` Output only. Further data for the suspended state. |

## State

Output only state of the request

| Enums ||
|---|---|
| `STATE_UNSPECIFIED` | State of the QueuedResource request is not known/set. |
| `CREATING` | The QueuedResource request has been received. We're still working on determining if we will be able to honor this request. |
| `ACCEPTED` | The QueuedResource request has passed initial validation/admission control and has been persisted in the queue. |
| `PROVISIONING` | The QueuedResource request has been selected. The associated resources are currently being provisioned (or very soon will begin provisioning). |
| `FAILED` | The request could not be completed. This may be due to some late-discovered problem with the request itself, or due to unavailability of resources within the constraints of the request (e.g., the 'valid until' start timing constraint expired). |
| `DELETING` | The QueuedResource is being deleted. |
| `ACTIVE` | The resources specified in the QueuedResource request have been provisioned and are ready for use by the end-user/consumer. |
| `SUSPENDING` | The resources specified in the QueuedResource request are being deleted. This may have been initiated by the user, or the Cloud TPU service. Inspect the state data for more details. |
| `SUSPENDED` | The resources specified in the QueuedResource request have been deleted. |
| `WAITING_FOR_RESOURCES` | The QueuedResource request has passed initial validation and has been persisted in the queue. It will remain in this state until there are sufficient free resources to begin provisioning your request. Wait times will vary significantly depending on demand levels. When demand is high, not all requests can be immediately provisioned. If you need more reliable obtainability of TPUs consider purchasing a reservation. To put a limit on how long you are willing to wait, use [timing constraints](https://cloud.google.com/tpu/docs/queued-resources#request_a_queued_resource_before_a_specified_time). |

## CreatingData

This type has no fields.
Further data for the creating state.

## AcceptedData

This type has no fields.
Further data for the accepted state.

## ProvisioningData

This type has no fields.
Further data for the provisioning state.

## FailedData

Further data for the failed state.

| JSON representation |
|---|
| ``` { "error": { object (`https://docs.cloud.google.com/tpu/docs/reference/rest/Shared.Types/ListOperationsResponse#Status`) } } ``` |

| Fields ||
|---|---|
| `error` | ``object (`https://docs.cloud.google.com/tpu/docs/reference/rest/Shared.Types/ListOperationsResponse#Status`)`` Output only. The error that caused the queued resource to enter the FAILED state. |

## DeletingData

This type has no fields.
Further data for the deleting state.

## ActiveData

This type has no fields.
Further data for the active state.

## SuspendingData

This type has no fields.
Further data for the suspending state.

## SuspendedData

This type has no fields.
Further data for the suspended state.

## StateInitiator

The initiator of the QueuedResource's SUSPENDING/SUSPENDED state.

| Enums ||
|---|---|
| `STATE_INITIATOR_UNSPECIFIED` | The state initiator is unspecified. |
| `USER` | The current QueuedResource state was initiated by the user. |
| `SERVICE` | The current QueuedResource state was initiated by the service. |

| ## Methods ||
|---|---|
| ### `https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources/create` | Creates a QueuedResource TPU instance. |
| ### `https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources/delete` | Deletes a QueuedResource TPU instance. |
| ### `https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources/get` | Gets details of a queued resource. |
| ### `https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources/list` | Lists queued resources. |
| ### `https://docs.cloud.google.com/tpu/docs/reference/rest/v2/projects.locations.queuedResources/reset` | Resets a QueuedResource TPU instance |