# List events

Source: https://docs.vlayers.ai/reference/events/list-events

`GET /v1/events` · scope `events:read`

Returns events after a cursor, oldest first, with the `cursor` to pass next time. Use it when you cannot receive webhooks or keep a stream open — a cron job, a serverless function. With `waitSec`, an empty page waits for the next event (long polling).

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

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `after` | query | string | no | The `cursor` from your previous page. Leave it out to start at the oldest event. Example: `"MDE5MmY1YjEtMGExYi03YzJk"` |
| `types` | query | string | no | Comma-separated event types, or a prefix with `.*`. Example: `"message.*"` |
| `conversationId` | query | string | no | Only events of this conversation. Example: `"0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21"` |
| `channel` | query | string | no | Only events of this channel's messages. Example: `"sms"` |
| `limit` | query | integer | no | How many items to return, 1–500. Default 100. Example: `20` |
| `from` | query | "oldest" \| "now" | no | Where to start without `after`: `oldest` (the default) or `now`. Example: `"now"` |
| `waitSec` | query | integer | no | When there is nothing new yet, wait up to this many seconds (1–25) for the first event. Example: `20` |

## Request

cURL:

```bash
curl "https://api.vlayers.ai/v1/events?types=message.*&limit=100" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { createVoiceLayerClient, listEvents } from '@voicelayer/api';

const client = createVoiceLayerClient({ apiKey: process.env.VOICELAYER_API_KEY!, throwOnError: true });

const { data } = await listEvents({
  client,
  query: {
    types: 'message.*',
    limit: 100
  }
});
console.log(data.events);
```

Python:

```python
import os
import voicelayer

config = voicelayer.Configuration(access_token=os.environ["VOICELAYER_API_KEY"])
with voicelayer.ApiClient(config) as client:
    api = voicelayer.EventsApi(client)
    result = api.list_events(
        types="message.*",
        limit=100,
    )
    print(result.events)
```

## Response `200`

```json
{
  "events": [
    {
      "id": "0192f5b1-0a1b-7c2d-8e3f-4a5b6c7d8e90",
      "type": "message.received",
      "createdAt": "2026-10-20T15:04:05.000Z",
      "livemode": false,
      "data": {
        "messageId": "0192f5b0-8d1f-7b62-8c3e-5f9a2b7d4e32",
        "conversationId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
        "channel": "sms",
        "direction": "inbound",
        "bindingId": null,
        "status": "received",
        "text": "Do you have a table for two tonight?",
        "author": null,
        "error": null,
        "metadata": {},
        "occurredAt": "2026-10-20T15:04:05.000Z"
      }
    }
  ],
  "cursor": "MDE5MmY1YjEtMGExYi03YzJk",
  "hasMore": false
}
```