# client.events

> The events methods of the morevoice Python SDK: The event log behind webhooks.

The event log behind webhooks. These methods are on `client.events`, where `client` is a `MoreVoice` client (see [the Python SDK](https://docs.morevoice.ai/sdk/python/#connect)). On `AsyncMoreVoice` the same methods are awaited. Each one returns the response object and raises an exception when the API answers with an error.

## `list()`

**List events.** Events in this mode, newest first, for the last 30 days. Filter by type (`type=call.*`, or several with `types[]`) and creation time (`created[gte]`…).

```python
# client.events
def list(self, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, type_: str | Unset = UNSET, types: _b.list[str] | Unset = UNSET, created: _m.EventsListCreated | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.Event]
```

`client.events.list()` · `await async_client.events.list()` · `GET /events` · [API reference](https://docs.morevoice.ai/api/operations/events_list/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no | How many objects to return, 1–100 (default 20). |
| `starting_after` | `string` | no | A cursor (`next_cursor`) or object ID: return the objects after it (older). |
| `ending_before` | `string` | no | A cursor or object ID: return the objects before it (newer). |
| `type` | `string` | no | Only events of this type. An event type (`call.ended`), a group (`call.*`) or `"*"` for every event. |
| `types` | `string[]` | no | Only events of these types (`types[]=call.ended&types[]=qa.*`). |
| `created` | `object` | no | Filter on the creation time: created[gte], created[gt], created[lte], created[lt] (ISO-8601). |

### Returns

A page of results (`EventList`): `data`, `has_more` and `next_cursor`.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for event in client.events.list():
    print(event)
```

## `retrieve()`

**Retrieve an event.** Returns one event: its type, the API version it was rendered in, and its payload (`data.object`), exactly as webhooks deliver it. Events are kept for 30 days.

```python
# client.events
def retrieve(self, id: str, *, more_voice_version: str | Unset = UNSET) -> _m.Event
```

`client.events.retrieve()` · `await async_client.events.retrieve()` · `GET /events/{id}` · [API reference](https://docs.morevoice.ai/api/operations/events_retrieve/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A event ID (`evt_…`). |

### Returns

`Event`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The event ID (also the `webhook-id` header of its deliveries). |
| `object` | `"event"` | Always `event`. |
| `type` | `"call.created" \| "call.started" \| "call.ringing" \| "call.answered" \| "call.transferred" \| "call.ended" \| "call.analyzed" \| "call.cost_finalized" \| …` | — |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `api_version` | `string` | — |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `org_id` | `string` | A org ID (prefix `org_`). |
| `data` | `object` | — |
| `request` | `object` | — |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

event = client.events.retrieve("evt_7Hk2Lm9Qp")
print(event)
```

## `stream()`

**Stream events as they happen.** Server-Sent Events: the same event envelopes as GET /v1/events and webhooks, live, for this key's mode. Filter with `types` (`call.*`, `campaign.completed`, …). Reconnect with `Last-Event-ID` (EventSource does it for you) to replay what you missed, up to 24 hours back; delivery is at-least-once, so dedupe on `id`. Counts against the key's stream limit (`concurrency_limit`, `limit_type: api_streams`).

`client.events.stream()` · `await async_client.events.stream()` · `GET /events/stream` · [API reference](https://docs.morevoice.ai/api/operations/events_stream/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `types` | `string \| string[]` | no | Only these event types: a type (`call.ended`), a group (`call.*`) or `"*"`; comma-separated or repeated. Default: every event. |
| `last_event_id` | `string` | no | Resume after this event, for clients that cannot send the `Last-Event-ID` header (the header wins when both are sent). |

### Returns

A stream of events (Server-Sent Events): iterate it, or `async for` it on `AsyncMoreVoice`.

### Example

```python
import os

import httpx

url = "https://api.morevoice.ai/v1/events/stream"
headers = {"Authorization": f"Bearer {os.environ['MOREVOICE_API_KEY']}", "Accept": "text/event-stream"}
with httpx.stream("GET", url, headers=headers, timeout=None) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line.startswith("data:"):
            print(line[5:].strip())
```