# History

> Conversations, contacts and messages stored by Messajo: filters, cursor pagination and how retention limits the time range.

Messajo stores what goes through the connections and lets you query it through the API with the `read` permission. Everything respects the key's connections: a key restricted to some connections only sees what belongs to them.

## Routes

| Route | Filters | Order |
|---|---|---|
| `GET /v1/conversations` | `connection_id`, `contact_id`, `window=open\|closed`, `since`, `until` (on `last_message_at`) | most recent `last_message_at` first |
| `GET /v1/conversations/{id}/messages` | `direction`, `type`, `since`, `until`, `order=desc\|asc` | `created_at` |
| `GET /v1/messages` | `connection_id`, `contact_id`, `conversation_id`, `direction`, `status`, `type`, `source`, `campaign_id`, `since`, `until`, `order` | `created_at` |
| `GET /v1/contacts` | `connection_id`, `channel`, `identity`, `q`, `since` | most recent `last_seen_at` first |

Each one has a by-id version (`GET /v1/conversations/{id}`, `GET /v1/messages/{id}`, `GET /v1/contacts/{id}`). Dates in ISO 8601.

- `identity` is an exact match on phone number (digits only), BSUID, Instagram @username, IGSID or PSID.
- `q` matches the start of the contact's name (up to 64 characters).
- `source` says where the message came from: `customer` (the contact), `api`, `campaign`, `business_app` (the phone app, under coexistence) or `history` (imported history); `campaign_id` returns only the messages of one campaign.
- Media shows up as part of the message, with an `id`. The file is at `GET /v1/media/{id}/content`.

## Cursor pagination

Every list returns `{ data, next_cursor }`. Pass `limit` (up to 100) and, for the next page, the `next_cursor` you received as `cursor`. You are done when `next_cursor` is `null`.

```bash
curl "https://api.messajo.com/v1/messages?conversation_id=cnv_...&limit=100" \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

```json
{
  "data": [
    {
      "id": "msg_...",
      "conversation_id": "cnv_...",
      "contact_id": "ctc_...",
      "direction": "inbound",
      "type": "text",
      "text": { "body": "Hi! Is the coupon still valid?" },
      "source": "customer",
      "status": "received",
      "campaign": null,
      "created_at": "2026-11-10T14:03:11.000Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJrIjpbIjIwMjYtMTEtMTBUMTQ6MDM6MTEuMDAwWiIsIm1zZ18uLi4iXX0"
}
```

- The cursor is opaque: do not build or change it. A broken cursor → `400` [`invalid_cursor`](/en/errors#invalid_cursor).
- The cursor stores a position, not a snapshot of the list: what arrives later does not duplicate or skip items already read.
- Use the same filters on every page.

With the [SDK](/en/sdk/typescript/), `paginate` follows the cursor for you:

```ts
for await (const message of messajo.paginate(messajo.messages.list, {
  conversation_id: "cnv_...",
})) {
  console.log(message.id);
}
```

## Time range and retention

Messages are stored by month. Every message query has a `since`/`until` range:

- without `since`, the start of the organization's [retention](/en/operate/data-privacy/#retention) applies (90 days by default); without `until`, now;
- a `since` older than the retention is clamped to the limit, without an error: whatever passed the deadline has already been deleted;
- short ranges respond faster.

Retention counts from when the data was **stored** in Messajo. The 6 months of history imported under coexistence are stored on the import day and leave together with the rest when the deadline passes.
