# List an endpoint's previews

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

`GET /v1/endpoints/{endpoint}/previews` · scope `workspace:read`

Shows the previews of an endpoint's versions: the live ones (asleep or awake) and the latest ended ones with the reason each ended (the customer ended it, it reached the end of its life, it was the oldest idle one when the workspace reached its limit, or the endpoint was deleted). `limit` is how many live previews the workspace may hold. A preview scales to zero after it has been idle for a while, costs nothing while asleep, and is billed at the `small` room rate while awake.

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

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `endpoint` | path | string | yes | The endpoint id: the first segment of its `run.vlayers.ai` URL. Example: `"x7k2p4q9m3vd"` |

## Request

cURL:

```bash
curl "https://api.vlayers.ai/v1/endpoints/$ENDPOINT_ID/previews" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

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

const voicelayer = new VoiceLayer();

const { previews } = await voicelayer.hosting.listEndpointPreviews('<endpoint-id>');
console.log(previews);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.hosting.list_endpoint_previews("<endpoint-id>")
print(result.previews)
```

## Response `200`

```json
{
  "previews": [
    {
      "id": "0192f5c1-5e6f-7a8b-9c0d-1e2f3a4b5c67",
      "endpointId": "x7k2p4q9m3vd",
      "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",
      "environment": "dev",
      "versionId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",
      "state": "asleep",
      "createdAt": "2026-10-20T15:04:05.000Z",
      "expiresAt": "2026-10-20T15:04:05.000Z",
      "lastRequestAt": "2026-10-20T15:04:05.000Z",
      "sleepsAt": null,
      "endedAt": null,
      "endedReason": null,
      "endedMessage": null,
      "routes": [
        {
          "kind": "api",
          "url": "https://run.vlayers.ai/x7k2p4q9m3vd--0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b/api"
        }
      ]
    }
  ],
  "limit": 3
}
```
