# List Instances - Documentation

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown is available with `Accept: text/markdown` and `.md` URL variants.

Source: /docs/api-reference/gpu-instance-list-instances

# List Instances

GET

/

gpu-instance

/

openapi

/

v1

/

gpu

/

instances

Try it

List Instances

cURL

```
curl --request GET \
--url https://api.novita.ai/gpu-instance/openapi/v1/gpu/instances \
--header 'Authorization: <authorization>' \
--header 'Content-Type: <content-type>'
```

```
import requestsurl = "https://api.novita.ai/gpu-instance/openapi/v1/gpu/instances"headers = { "Content-Type": "<content-type>", "Authorization": "<authorization>"}response = requests.get(url, headers=headers)print(response.text)
```

```
const options = { method: 'GET', headers: {'Content-Type': '<content-type>', Authorization: '<authorization>'}};fetch('https://api.novita.ai/gpu-instance/openapi/v1/gpu/instances', options) .then(res => res.json()) .then(res => console.log(res)) .catch(err => console.error(err));
```

```
<?php$curl = curl_init();curl_setopt_array($curl, [ CURLOPT_URL => "https://api.novita.ai/gpu-instance/openapi/v1/gpu/instances", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: <authorization>", "Content-Type: <content-type>" ],]);$response = curl_exec($curl);$err = curl_error($curl);curl_close($curl);if ($err) { echo "cURL Error #:" . $err;} else { echo $response;}
```

```
package mainimport (	"fmt"	"net/http"	"io")func main() {	url := "https://api.novita.ai/gpu-instance/openapi/v1/gpu/instances"	req, _ := http.NewRequest("GET", url, nil)	req.Header.Add("Content-Type", "<content-type>")	req.Header.Add("Authorization", "<authorization>")	res, _ := http.DefaultClient.Do(req)	defer res.Body.Close()	body, _ := io.ReadAll(res.Body)	fmt.Println(string(body))}
```

```
HttpResponse<String> response = Unirest.get("https://api.novita.ai/gpu-instance/openapi/v1/gpu/instances") .header("Content-Type", "<content-type>") .header("Authorization", "<authorization>") .asString();
```

```
require 'uri'require 'net/http'url = URI("https://api.novita.ai/gpu-instance/openapi/v1/gpu/instances")http = Net::HTTP.new(url.host, url.port)http.use_ssl = truerequest = Net::HTTP::Get.new(url)request["Content-Type"] = '<content-type>'request["Authorization"] = '<authorization>'response = http.request(request)puts response.read_body
```

200

```
{
"instances": [
{
"id": "<string>",
"name": "<string>",
"clusterId": "<string>",
"clusterName": "<string>",
"status": "<string>",
"imageUrl": "<string>",
"imageAuthId": "<string>",
"command": "<string>",
"entrypoint": "<string>",
"cpuNum": "<string>",
"memory": "<string>",
"gpuNum": "<string>",
"portMappings": [
{
"port": 123,
"type": "<string>"
}
],
"productId": "<string>",
"productName": "<string>",
"rootfsSize": 123,
"volumeMounts": [
{
"type": "<string>",
"size": "<string>",
"id": "<string>",
"mountPath": "<string>"
}
],
"statusError": {
"state": "<string>",
"message": "<string>"
},
"envs": [
{
"key": "<string>",
"value": "<string>"
}
],
"kind": "<string>",
"billingMode": "<string>",
"endTime": "<string>",
"spotStatus": "<string>",
"spotReclaimTime": "<string>"
}
]
}
```

##

[​](#request-headers)

Request Headers

[​](#param-content-type)

Content-Type

string

required

Enum: `application/json`

[​](#param-authorization)

Authorization

string

required

Bearer authentication format, for example: Bearer {{API Key}}.

##

[​](#query-parameters)

Query Parameters

[​](#param-page-size)

pageSize

integer

required

Maximum number of items returned per page. Integer, value >= 0.

[​](#param-page-num)

pageNum

integer

required

Page number to retrieve. Integer, value >= 0.

[​](#param-name)

name

string

Instance name (supports fuzzy search). String, length limit: 0-255 characters.

[​](#param-product-name)

productName

string

Product name (supports fuzzy search). String, length limit: 0-255 characters.

[​](#param-status)

status

string

Instance status. String, length limit: 0-63 characters. Possible values:

- `toCreate`: Pending creation

- `creating`: Creating

- `pulling`: Pulling image

- `running`: Running

- `toStart`: Pending start

- `starting`: Starting

- `toStop`: Pending stop

- `stopping`: Stopping

- `exited`: Stopped

- `toRestart`: Pending restart

- `restarting`: Restarting

- `toRemove`: Pending deletion

- `removing`: Deleting

- `removed`: Deleted

- `toReset`: Pending reset (upgrade)

- `resetting`: Resetting

- `migrating`: Migrating

- `freezing`: Freezing

##

[​](#response)

Response

[​](#param-instances)

instances

object[]

required

Instance information.

Hide properties

[​](#param-id)

id

string

required

Instance ID.

[​](#param-name-1)

name

string

required

Instance name.

[​](#param-cluster-id)

clusterId

string

required

Cluster ID.

[​](#param-cluster-name)

clusterName

string

Cluster name.

[​](#param-status-1)

status

string

required

Instance status.

[​](#param-image-url)

imageUrl

string

required

Container image URL.

[​](#param-image-auth-id)

imageAuthId

string

Image repository authentication information.

[​](#param-command)

command

string

Container startup command.

[​](#param-entrypoint)

entrypoint

string

Container startup entrypoint.

[​](#param-cpu-num)

cpuNum

string

required

Number of CPU cores for the instance.

[​](#param-memory)

memory

string

required

Memory size of the instance (GB).

[​](#param-gpu-num)

gpuNum

string

required

Number of GPUs for the instance.

[​](#param-port-mappings)

portMappings

object[]

Instance port information.

Show properties

[​](#param-port)

port

integer

required

Port value.

[​](#param-type)

type

string

required

Port type.

[​](#param-product-id)

productId

string

required

Product ID used to deploy the instance.

[​](#param-product-name-1)

productName

string

required

Product name used to deploy the instance.

[​](#param-rootfs-size)

rootfsSize

integer

required

Root filesystem size (GB).

[​](#param-volume-mounts)

volumeMounts

object[]

Instance storage configuration.

Show properties

[​](#param-type-1)

type

string

Storage type. Values:

- network: Cloud storage.

- local: Local storage.

[​](#param-size)

size

string

Storage capacity.

[​](#param-id-1)

id

string

Cloud storage ID. Returned when type = network.

[​](#param-mount-path)

mountPath

string

Storage mount path.

[​](#param-status-error)

statusError

object

Error information when instance creation fails or the instance is unavailable.

Show properties

[​](#param-state)

state

string

Abnormal instance status.

[​](#param-message)

message

string

Error message.

[​](#param-envs)

envs

object[]

Instance environment variable information.

Show properties

[​](#param-key)

key

string

Environment variable name.

[​](#param-value)

value

string

Environment variable value.

[​](#param-kind)

kind

string

Instance type.

[​](#param-billing-mode)

billingMode

string

required

Billing mode for the instance. Values:

- onDemand: Pay-as-you-go billing.

- monthly: Subscription (monthly or yearly) billing.

- spot: Spot instance billing.

[​](#param-end-time)

endTime

string

Expiration time for subscription instances. For pay-as-you-go instances, returns -1.

[​](#param-spot-status)

spotStatus

string

Spot instance status. Values:

- `running`: Running

- `notified`: Notified for reclaim

- `reclaiming`: Being reclaimed

- `terminated`: Terminated

[​](#param-spot-reclaim-time)

spotReclaimTime

string

Spot instance reclaim time. Value “0” means reclaim has not started.

Last modified on December 24, 2025