> For the complete documentation index, see [llms.txt](https://docs.nebulablock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nebulablock.com/api-reference/platform-api/list-products/list-instances.md). # List Instances List the instances currently running on your Nebula Block account. Return a list of all active instances. ## HTTP Request `GET` `{API_URL}/computing/instances` ## Query Parameters | Parameter | Requirement | Type | Description | | --------- | ----------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `offset` | Optional | `int` | **Page number**, starting at `1`. Despite the name this is not a row offset — the API computes `(offset - 1) * limit` internally. Defaults to `1`, minimum `1` | | `limit` | Optional | `int` | Results per page. Defaults to `10`, maximum `100` | | `team_id` | Optional | `int` | Which instances to include, alongside your own. See below and [Teams](/account/teams.md) | | `type` | Optional | `int` | An internal product classification. Leave it out unless support has told you otherwise | ### How `team_id` scopes the result `team_id` widens or narrows the list; it never replaces your own instances with someone else's. | Value | Returns | | --------- | ------------------------------------------------------------------------------------------------------------------------ | | omitted | Your own instances **plus** those of every team you hold instance-read permission on | | a team ID | Your own instances **plus** that team's instances. Returns an error if you have no instance-read permission on that team | | `-1` | Your own personal instances only, with every team's instances excluded | ## Response Attributes #### data `array` A flat array of your current instances. Empty, with `status` still `success`, when there are none. Each entry contains: * **id** `string`: The unique identifier of the instance. Pass this as `{id}` to [Get Instance](/api-reference/platform-api/list-products/get-instance.md), the power endpoints, and [Delete Instance](/api-reference/platform-api/list-products/delete-instance.md). * **name** `string`: The user-defined name of the instance. Carries the same value as `host_name`; prefer whichever you already use. * **host\_name** `string`: The user-defined name of the instance. * **dc\_id** `number`: Identifier of the data center hosting the instance. * **region** `string`: The region the instance runs in. * **product\_type** `string`: The form factor — `Virtual Machine`, `Baremetal`, or `Container`. * **cpu\_cores** `number`: The number of CPU cores. * **cpu\_count** `number`: The number of CPUs, alongside `cpu_cores`. * **cpu\_model** `string`: The CPU model. * **ram** `number`: The amount of RAM in gigabytes. * **gpu** `string`: The full GPU model name, for example `A100-80G-PCIe`. * **gpu\_type** `string`: The GPU family, for example `A100`. * **gpu\_count** `number`: The number of GPUs attached to the instance. * **disk\_size** `number`: The root disk size in gigabytes. * **ephemeral** `number`: The ephemeral disk size in gigabytes. * **public\_ipv4** `string`: The public IPv4 address of the instance, or `null` before one is assigned. * **price\_per\_hour** `decimal`: The hourly price of the instance in USD. * **os** `string`: The operating system of the instance. * **status** `string`: The status of the instance, for example `Deploying`, `Running`, `Stopped`. * **is\_spot** `boolean`: Whether the instance is running on spot capacity. * **created\_at** `number`: Unix timestamp in seconds for when the instance record was created. * **started\_at** `number`: Only set on a reserved instance, where it holds the booked start of the reservation as a unix timestamp. `null` on on-demand instances. * **ended\_at** `number`: Only set on a reserved instance, where it holds the booked end of the reservation as a unix timestamp. `null` on on-demand instances. * **type** `number`: An internal product classification. Usually `null`. * **team\_id** `number`: The owning team, or `null` for a personal instance. * **team** `object`: The owning team as `{id, name, role, permissions}`, or `null` for a personal instance. * **user** `object`: The owner as `{id, name, email}`. > **Note:** The response also carries fields used by the console UI, such as `capabilities`. Treat anything not listed here as internal and subject to change. #### message `string` A description of the status of the request. #### total\_instance `number` The total number of matching instances, for pagination. This sits **alongside** `data` at the top level of the response, not inside it. #### status `string` Indicates the result of the request.\ **success** signifies success, while **failed** indicates an error. ## Example #### Request ```bash curl -X GET '{API_URL}/computing/instances' \ -H 'Authorization: Bearer {ACCESS_TOKEN}' \ -H 'Content-Type: application/json' \ ``` #### Response ```json { "data": [ { "id": "7b3e4c21-8f2a-4d19-9c3e-1a2b3c4d5e6f", "name": "demo", "host_name": "demo", "dc_id": 2, "region": "CANADA", "product_type": "Virtual Machine", "cpu_cores": 28, "cpu_count": 1, "cpu_model": "AMD EPYC 7763", "ram": 58, "gpu": "RTX-A6000", "gpu_type": "RTX", "gpu_count": 1, "disk_size": 100, "ephemeral": 1500, "public_ipv4": "38.80.81.128", "price_per_hour": 0.679, "os": "Ubuntu Server 22.04 LTS", "status": "Running", "is_spot": false, "created_at": 1730729510, "started_at": null, "ended_at": null, "type": null, "team_id": null, "team": null, "user": { "id": 1234, "name": "Demo User", "email": "demo@example.com" } } ], "total_instance": 1, "message": "All instances retrieved successfully", "status": "success" } ```