# GET /v1/events

> The same events as a list you can pull, for anything you missed.

In [Webhooks and events API](https://vestra.ai/developers/reference/api/webhooks-and-events.md): Where events go, how each delivery went, and the record of every event.

Send `Authorization: Bearer vk_test_...` on every call.

The same events as a list you can pull, for anything you missed.

Your API key, scope `runtime` or `all`. On the card: [`events`](https://vestra.ai/developers/events.md). Every call here is a checked sample.

## Request

Query:

- `limit` (`integer`): How many items per page, 1 to 100. Default 20.
- `cursor` (`string`): Where to go on from: the `next_cursor` of the page before, unchanged. Absent: the first page.
- `type` (`string`): Only events of this type.
- `user_id` (`string`): Only this user's, by your id for them.
- `task_id` (`string`): Only this task's (task_...).
- `created_after` (`string (date and time)`): Only events after this ISO 8601 time.
- `created_before` (`string (date and time)`): Only events before this ISO 8601 time.
- `after` (`string`): Only events after this one (evt_...), oldest first: poll with the last one you saw and you miss nothing. Without it, newest first.

## Answers 200

- `data` (`object[]`): The items on this page.
  - `id` (`string`): The event (evt_...): the same on every retry, so use it to skip one you already took. Example: `evt_4hq`.
  - `object` (`"event"`): Always event.
  - `type` (`string`): An event a webhook carries: every event of the catalog but the six that ride only the stream (message.delta, task.progress, usage.updated, screen.control, error and ping). Limits: one of 28 values. Example: `task.completed`.
  - `mode` (`"live" | "test"`): The mode it happened in: test or live.
  - `created_at` (`string`): When it happened, as an ISO 8601 time.
  - `user_id` (`string | null`): Your id for the user it concerns; null for your company's own Bash, or when it concerns no user.
  - `task_id` (`string | null`): The task it concerns (task_...); null when none.
  - `conversation_id` (`string | null`): The conversation it concerns (conv_...); null when none.
  - `data` (`map of any`): What it says: its fields depend on its type, as the events reference lists them.
- `next_cursor` (`string | null`): Send it as `cursor` for the next page; null on the last page.

## Code

**TypeScript**

```ts
const events = await vestra.events.list();
```

**Python**

```python
events = vestra.events.list()
```

**CLI**

```bash
vestra events
```

**HTTP**

```bash
# Stream a conversation live. If the connection drops, reconnect with the last seq you saw.
curl -N "$VESTRA_BASE_URL/v1/conversations/conv_8f2k/events" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Last-Event-ID: 41"

# Read the same events as JSON. You get them in pages, after the seq you give.
curl "$VESTRA_BASE_URL/v1/conversations/conv_8f2k/events?format=json&after=41" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# Read a task afterwards. You get every step of one task, with tokens and cost per turn.
curl "$VESTRA_BASE_URL/v1/tasks/task_91d/trace" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# Send events to your server. Register a URL and the events it wants. The signing secret is shown only once.
curl "$VESTRA_BASE_URL/v1/webhooks" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/vestra", "events": ["task.completed", "interaction.created", "usage.cap_reached"] }'

# Catch up on what you missed. List the events your webhooks were sent, newest first.
curl "$VESTRA_BASE_URL/v1/events?type=task.failed" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

**MCP**

```json
{
  "method": "tools/call",
  "params": {
    "name": "events",
    "arguments": { "user": "traveller-42", "conversation": "conv_8f2k", "after": 0 }
  }
}
```