# Get Instance - 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-get-instance

# Get Instance

GET

/

gpu-instance

/

openapi

/

v1

/

gpu

/

instance

Try it

Get Instance

cURL

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

200

```
{
"id": "<string>",
"name": "<string>",
"clusterId": "<string>",
"clusterName": "<string>",
"imageUrl": "<string>",
"imageAuthId": "<string>",
"command": "<string>",
"entrypoint": "<string>",
"cpuNum": "<string>",
"memory": "<string>",
"gpuNum": "<string>",
"status": "<string>",
"statusError": {
"state": "<string>",
"message": "<string>"
},
"network": {
"id": "<string>",
"ip": "<string>"
},
"portMappings": [
{
"port": 123,
"endpoint": "<string>",
"type": "<string>"
}
],
"volumeMounts": [
{
"type": "<string>",
"size": 123,
"id": "<string>",
"mountPath": "<string>"
}
],
"node": [
{
"maxRootfsSize": 123
}
],
"jobs": [
{
"id": "<string>",
"type": "<string>"
}
],
"envs": [
{
"key": "<string>",
"value": "<string>"
}
],
"connectComponentSSH": {
"sshCommand": "<string>",
"password": "<string>",
"isRunning": true
},
"connectComponentWebTerminal": {
"address": "<string>",
"username": "<string>",
"password": "<string>",
"isRunning": true
},
"connectComponentJupyter": {
"port": 123,
"address": "<string>",
"isRunning": true
},
"connectComponentLog": {
"systemLogAddress": "<string>",
"instanceLogAddress": "<string>",
"isRunning": true
},
"kind": "<string>",
"billingMode": "<string>",
"endTime": "<string>",
"freeStorageSize": 123,
"keepDataDay": 123
}
```

##

[​](#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-instance-id)

instanceId

string

required

ID of the instance being queried.

##

[​](#response)

Response

[​](#param-id)

id

string

required

Instance ID.

[​](#param-name)

name

string

required

Instance name.

[​](#param-cluster-id)

clusterId

string

required

Cluster ID.

[​](#param-cluster-name)

clusterName

string

required

Name of the cluster.

[​](#param-image-url)

imageUrl

string

required

Container image URL.

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

imageAuthId

string

required

Image registry authentication information.

[​](#param-command)

command

string

required

Container startup command.

[​](#param-entrypoint)

entrypoint

string

required

Container startup entrypoint.

[​](#param-cpu-num)

cpuNum

string

required

Number of CPU cores allocated to the instance.

[​](#param-memory)

memory

string

required

Memory size allocated to the instance, in GB.

[​](#param-gpu-num)

gpuNum

string

required

Number of GPU cards allocated to the instance.

[​](#param-status)

status

string

required

Instance status. 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

[​](#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-network)

network

object

VPC network information for the instance.

Show properties

[​](#param-id-1)

id

string

VPC network ID.

[​](#param-ip)

ip

string

Instance IP address.

[​](#param-port-mappings)

portMappings

object[]

required

Instance port mapping information.

Show properties

[​](#param-port)

port

integer

required

Port number.

[​](#param-endpoint)

endpoint

string

required

Endpoint.

[​](#param-type)

type

string

required

Protocol type.

[​](#param-volume-mounts)

volumeMounts

object[]

Storage configuration for the instance.

Show properties

[​](#param-type-1)

type

string

Storage type. Possible values:

- network: Cloud storage.

- local: Local storage.

[​](#param-size)

size

number

Storage capacity.

[​](#param-id-2)

id

string

Cloud storage ID. Only present when the storage type is “network”.

[​](#param-mount-path)

mountPath

string

Mount path for the storage.

[​](#param-node)

node

object[]

Node information.

Show properties

[​](#param-max-rootfs-size)

maxRootfsSize

number

Maximum available system disk size.

[​](#param-jobs)

jobs

object[]

Tasks currently running on the instance.

Show properties

[​](#param-id-3)

id

string

Task ID.

[​](#param-type-2)

type

string

Task type. Currently, only saveImage is supported, which indicates saving an image.

[​](#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-connect-component-ssh)

connectComponentSSH

object

Instance SSH connection information.

Show properties

[​](#param-ssh-command)

sshCommand

string

Command for SSH remote login.

[​](#param-password)

password

string

Password for SSH remote login.

[​](#param-is-running)

isRunning

boolean

Whether SSH remote login is active.

[​](#param-connect-component-web-terminal)

connectComponentWebTerminal

object

Instance WebSSH connection information.

Show properties

[​](#param-address)

address

string

Address for web-based remote login.

[​](#param-username)

username

string

Username for web-based remote login.

[​](#param-password-1)

password

string

Password for web-based remote login.

[​](#param-is-running-1)

isRunning

boolean

Whether web-based remote login is active.

[​](#param-connect-component-jupyter)

connectComponentJupyter

object

Jupyter connection information for the instance (if available).

Show properties

[​](#param-port-1)

port

integer

Connection port.

[​](#param-address-1)

address

string

Connection address.

[​](#param-is-running-2)

isRunning

boolean

Whether Jupyter remote login is active.

[​](#param-connect-component-log)

connectComponentLog

object

Instance log connection information (HTTP Stream).

Show properties

[​](#param-system-log-address)

systemLogAddress

string

System log address.

[​](#param-instance-log-address)

instanceLogAddress

string

Instance log address.

[​](#param-is-running-3)

isRunning

boolean

Whether log connection is active.

[​](#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-free-storage-size)

freeStorageSize

integer

Free system disk size (GB).

[​](#param-keep-data-day)

keepDataDay

integer

Number of days data is retained after the instance is shut down.

Last modified on December 24, 2025