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

# List a contact's chat sessions

> GET /v1/contacts/{id}/sessions: a contact's visits to the chat widget, with page, IP address and browser

Returns the contact's visits to the chat widget, oldest first. A session holds what the browser sent: the page, the IP address, the browser and the language. The chat text itself is in the ticket's messages, see [List messages](https://docs.replyful.com/api-reference/conversations/messages.md).

```http theme={null}
GET /v1/contacts/{id}/sessions
```

## Authentication

Bearer token in the `Authorization` header. A read-only key is enough. See [Authentication](https://docs.replyful.com/api-reference/authentication.md).

```http theme={null}
Authorization: Bearer rfl_live_...
```

## Path parameters

**id** `string` *required*

Contact ID, usually prefixed with `con_`.

## Query parameters

**limit** `integer` (default: 20)

Number of sessions per page. Range `1` to `100`.

**startingAfter** `string`

Opaque cursor from the previous response's `nextCursor`. See [Pagination](https://docs.replyful.com/api-reference/pagination.md).

## Response

Returns a [list envelope](https://docs.replyful.com/api-reference/pagination.md#response-shape) containing `Session` objects. The list is empty for a contact who never used the chat widget.

### The Session object

**id** `string`

Unique identifier.

**object** `string`

Always `"session"`.

**contactId** `string`

The contact's ID.

**channelId** `string`

The chat [channel](https://docs.replyful.com/api-reference/channels/retrieve.md) the visit was on.

**originUrl** `string | null`

The page the widget was opened on, if known.

**ipAddress** `string | null`

The visitor's IP address, if stored.

**userAgent** `string | null`

The browser's `User-Agent` header, if stored.

**acceptLanguage** `string | null`

The browser's `Accept-Language` header, if stored.

**createdAt** `string`

ISO 8601 UTC timestamp of when the session started.

**lastSeenAt** `string`

ISO 8601 UTC timestamp of the visitor's latest activity in the session.

## Examples

### List a contact's sessions

```bash curl theme={null}
curl "https://api.replyful.com/v1/contacts/con_9dKmT3xWq6bYrN8cJfA2e/sessions?limit=100" \
  -H "Authorization: Bearer rfl_live_..."
```

```ts Node.js theme={null}
const res = await fetch(
  "https://api.replyful.com/v1/contacts/con_9dKmT3xWq6bYrN8cJfA2e/sessions?limit=100",
  { headers: { Authorization: `Bearer ${process.env.REPLYFUL_API_KEY}` } },
);
const { data, hasMore, nextCursor } = await res.json();
```

```json Response theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "Vq3nT8xKb2mWf6cR9yJd4",
      "object": "session",
      "contactId": "con_9dKmT3xWq6bYrN8cJfA2e",
      "channelId": "k3v9x2qa",
      "originUrl": "https://shop.example.com/orders/4821",
      "ipAddress": "203.0.113.42",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15",
      "acceptLanguage": "sv-SE,sv;q=0.9,en;q=0.8",
      "createdAt": "2026-04-29T14:29:31Z",
      "lastSeenAt": "2026-04-29T14:41:05Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "url": "/v1/contacts/con_9dKmT3xWq6bYrN8cJfA2e/sessions"
}
```

## Error responses

| Status | `error.code` | When |
| - | - | - |
| `401` | `missing_api_key` | The `Authorization` header is absent. |
| `401` | `invalid_api_key` | The token is malformed, unknown, or archived. |
| `404` | `contact_not_found` | The contact does not exist, belongs to another organization, or has been erased. |
| `422` | `invalid_path_parameter` | The `id` path parameter is not a valid contact ID. |
| `422` | `invalid_query_parameter` | A query parameter failed validation. |
| `422` | `invalid_cursor` | The `startingAfter` cursor could not be decoded. |
| `429` | `too_many_requests` | Rate limit exceeded. Honor `Retry-After`. |

See [Errors](https://docs.replyful.com/api-reference/errors.md) for the full error envelope reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.