> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentline.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Receive durable live events through the Agent Relay or fallback mailbox.

# Events

For live caller turns, use the outbound **Agent Relay**. It reconnects, retains
events until ACK, and works without a public inbound URL. Use the mailbox for
non-live fallback awareness when neither relay nor webhook is available.

See [Agent Relay](/guides/relay) for the two-command runtime setup.

## Poll (fallback, consume once)

`poll` returns pending events **and deletes them** — treat it as a
one-time read.

<CodeGroup>
  ```python theme={null}
  result = client.events.poll(event_type="call.completed", limit=50)
  for e in result["events"]:
      print(e["event_type"], e["payload"])
  ```

  ```javascript theme={null}
  const result = await client.events.poll({ eventType: "call.completed", limit: 50 });
  for (const e of result.events) console.log(e.event_type, e.payload);
  ```
</CodeGroup>

Each event has `{ event_id, agent_id, event_type, payload, created_at }`.
Common `event_type`s include `call.utterance`, `call.completed`, `call.failed`,
`call.owner_task`, and `sms.received`.

## Peek (non-destructive)

`peek` previews what's queued **without** consuming it — handy to check before
committing to retrieve.

<CodeGroup>
  ```python theme={null}
  client.events.peek(agent_id=agent.id)
  ```

  ```javascript theme={null}
  await client.events.peek({ agentId: agent.id });
  ```
</CodeGroup>

<Tip>
  Prefer [Agent Relay](/guides/relay) for live calls, then [webhooks](/guides/webhooks)
  for a public inbound integration. Use the mailbox for fallback polling only.
</Tip>