# History & listing

> Read full conversation history with a contact, or list recent messages across the workspace.

## Conversation history

GET https://beam.aisync.link/v1/conversations/:phone · optional ?limit=50 (max 500)
curlResponseCopy
```
curl "https://beam.aisync.link/v1/conversations/+15551234567" \
  -H "x-api-key: YOUR_WORKSPACE_KEY"
```

```
{
  "phone": "+15551234567",
  "messages": [
    { "id": "41", "direction": "outbound", "channel": "imessage",
      "body": "Hey Sarah...", "status": "sent", "sender": "human",
      "ts": "2026-08-21T19:16:02.000Z" },
    { "id": "42", "direction": "inbound", "body": "first time! kind of nervous lol",
      "status": "received", "ts": "2026-08-21T19:21:44.000Z" }
  ]
}
```

The sender field tells you who wrote each outbound message: human (inbox or API) or bot (the assistant). Useful for QA and analytics.

## List messages

GET https://beam.aisync.link/v1/messages/list · filters: ?to=+1555..., ?status=queued|sent|failed, ?limit=50 (max 200). Newest first.
curlCopy
```
curl "https://beam.aisync.link/v1/messages/list?status=queued&limit=20" \
  -H "x-api-key: YOUR_WORKSPACE_KEY"
```

Prefer webhooks for real-timePolling these endpoints works, but for reacting to new messages as they happen, use event webhooks and keep listing for reconciliation and reporting.