List an endpoint's previews

GET
/v1/endpoints/{endpoint}/previews

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.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

endpoint*string

The endpoint id: the first segment of its run.vlayers.ai URL.

Response Body

The endpoint's live previews and the latest ended ones, each with why it ended, and the workspace's limit

application/json
  1. response
previews*array<>
limit*integer
Example Request
curl "https://api.vlayers.ai/v1/endpoints/$ENDPOINT_ID/previews" \  -H "Authorization: Bearer $VOICELAYER_API_KEY"
Example Response
{  "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}