> ## 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 Leads

> Paginated leads captured by a widget.

## 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 leads to skip.
</ParamField>

<ParamField query="search" type="string">
  Case-insensitive match against captured lead fields.
</ParamField>

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

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

## Response

<ResponseField name="leads" type="array">
  Each lead: `id`, `lead_data` (the captured fields), `session_id`, `ip_country`, `referrer_url`, `created_at`.
</ResponseField>

<ResponseField name="total" type="number">
  Total leads 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/leads?limit=50" \
  -H "Authorization: Bearer $THEO_API_KEY"
```