# List your rooms

Source: https://docs.vlayers.ai/reference/hosting/list-rooms

`GET /v1/rooms` · scope `workspace:read`

Lists the rooms your hosted agents run in: one per warm copy of a version, with its state (`starting`, `ready`, `draining`, and the ones that ended). Use it to see what is running, which version each room serves and why one is not ready. By default only rooms that are not over are listed; `scope=all` adds the ones that ended, were lost or failed in the last week.

Requires an API key with the `workspace:read` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `agentId` | query | string | no | Only the rooms of this agent. Example: `"0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78"` |
| `environment` | query | "dev" \| "stg" \| "prd" | no | Only the rooms of one environment: `dev`, `stg` or `prd`. Example: `"prd"` |
| `scope` | query | "live" \| "all" | no | `live` (the default) lists rooms that are not over; `all` adds the ended, lost and failed ones from the last week. Example: `"live"` |
| `limit` | query | integer | no | How many items to return, 1–200. Default 100. Example: `20` |

## Request

cURL:

```bash
curl "https://api.vlayers.ai/v1/rooms?scope=live&limit=20" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { rooms } = await voicelayer.hosting.listRooms({ scope: 'live', limit: 20 });
console.log(rooms);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.hosting.list_rooms(scope="live", limit=20)
print(result.rooms)
```

## Response `200`

```json
{
  "rooms": [
    {
      "id": "room_0192f5d4-8b9c-7dae-8f3a-4b5c6d7e8f90",
      "workspaceId": "0192f5a1-5e6f-7a7b-8c8d-9e0f1a2b3c45",
      "environment": "prd",
      "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",
      "versionId": "0192f5d5-9cad-7ebf-9a4b-5c6d7e8f9012",
      "manifestHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "imageDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "replica": 0,
      "sizeClass": "small",
      "purpose": "warm",
      "state": "ready",
      "runtimeClass": "kata-clh-4-2",
      "shimVersion": "1.0.0",
      "replacementOf": null,
      "createdAt": "2026-10-20T15:04:05.000Z",
      "endedAt": null
    }
  ]
}
```
