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

# Widget Analytics

> Aggregated sessions, leads, messages, conversion, and geo breakdown for a widget.

Returns KPIs for the selected window, the previous period for comparison, daily time series, and top referrers/countries.

## 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="window" type="string" default="30d">
  Reporting window: `7d`, `30d`, or `90d`.
</ParamField>

## Response

<ResponseField name="window" type="string">
  The window that was applied.
</ResponseField>

<ResponseField name="kpi" type="object">
  `total_sessions`, `total_leads`, `total_messages`, `conversion_rate`, `avg_session_duration_seconds`, `avg_messages_per_session`, `identified_sessions`, `anonymous_sessions`.
</ResponseField>

<ResponseField name="previous_period_kpi" type="object">
  The same KPI shape for the immediately preceding period.
</ResponseField>

<ResponseField name="series" type="object">
  Daily time series: `sessions`, `leads`, `messages`, each an array of `{ day, count }`.
</ResponseField>

<ResponseField name="top_referrers" type="array">
  Up to 10 `{ url, count }` entries.
</ResponseField>

<ResponseField name="top_countries" type="array">
  Up to 10 `{ country, count }` entries.
</ResponseField>

<ResponseField name="top_country_coords" type="array">
  Map-ready `{ country, name, lat, lng, count }` entries for the top countries.
</ResponseField>

## Example

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