---
title: "List Agent VMs"
url: https://hexelstudio.com/docs/api/compute/vms/list
---

# List Agent VMs

**GET** `/compute/v1/vms`

Returns VMs scoped to the caller's org

## Query parameters

- `state: optional string`

  Filter by state

- `tier: optional string`

  Filter by tier

- `limit: optional integer`

  Limit results

- `offset: optional integer`

  Offset results

## Headers

- `Authorization: string`

  `Bearer <token>`. STS access token. Obtain via POST https://sts.hexelstudio.com/token with X-API-Key header.

## Returns

`200` OK (`array of AgentVM`)

- `allocated_at: optional string`

- `created_at: optional string`

- `expires_at: optional string`

- `id: optional string`

- `metadata: optional map[string]`

- `released_at: optional string`

- `skills: optional array of string`

- `state: optional string`

- `tier: optional string`

- `token: optional string`

- `ttl_seconds: optional integer`

## Errors

- `500` Internal Server Error

## Example

```bash
curl --request GET \
  --url 'https://compute.hexelstudio.com/compute/v1/vms' \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

### Response (200)

```json
[
  {
    "allocated_at": "2026-01-01T00:00:00Z",
    "created_at": "2026-01-01T00:00:00Z",
    "expires_at": "2026-01-01T00:00:00Z",
    "id": "string",
    "metadata": {
      "key": "string"
    },
    "released_at": "2026-01-01T00:00:00Z",
    "skills": [
      "string"
    ],
    "state": "string",
    "tier": "string",
    "token": "string",
    "ttl_seconds": 0
  }
]
```

### Response (500)

```json
{
  "code": 0,
  "error_code": "string",
  "message": "string"
}
```