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

# List Widget Conversations

> Paginated visitor sessions for a widget, with a one-line preview per session.

## Authentication

Requires a Bearer token (API key) or a dashboard session.

## Path Parameters

<ParamField path="id" type="string" required>
  The widget config UUID.
</ParamField>

## Query Parameters

<ParamField query="limit" type="number" default="50">
  Page size (max 200).
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of sessions to skip.
</ParamField>

<ParamField query="from" type="string">
  ISO timestamp lower bound (inclusive).
</ParamField>

<ParamField query="to" type="string">
  ISO timestamp upper bound (inclusive).
</ParamField>

<ParamField query="has_lead" type="string">
  `true` or `false` — filter by whether a lead was captured.
</ParamField>

<ParamField query="status" type="string">
  `active`, `completed`, or `all`.
</ParamField>

## Response

<ResponseField name="conversations" type="array">
  Each session: `session_id`, `visitor_id`, `ip_country`, `city`, `page_url`, `started_at`, `ended_at`, `last_seen_at`, `message_count`, `lead_captured`, `lead_data`, `first_message` (preview), `duration_seconds`, `referrer_url`, `takeover_status`.
</ResponseField>

<ResponseField name="total" type="number">
  Total sessions matching the filter.
</ResponseField>

<ResponseField name="limit" type="number" />

<ResponseField name="offset" type="number" />

## Example

```bash curl theme={null}
curl "https://www.hitheo.ai/api/v1/iframes/CONFIG_ID/conversations?status=active" \
  -H "Authorization: Bearer $THEO_API_KEY"
```