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

# Events

> The Events explorer: a raw, chronological log of custom events (clicks, downloads, forms, outbound links, copies, custom track() calls, and errors), a chart of

The Events explorer: a raw, chronological log of custom events (clicks, downloads, forms, outbound links, copies, custom `track()` calls, and errors), a chart of counts over time, and a per-event property drill-down. A dedicated Page titles list and its own filter-value autocomplete live here too, since both power the same explorer UI.

A site is addressed by `{siteKey}` (UUID or domain). All endpoints require `Authorization: Bearer {token}` and accept the shared `range`/`from`/`to` and filter query parameters described in [Conventions](/api/conventions).

### List events

```http theme={null}
GET /api/sites/{siteKey}/stats/events
```

A chronological log of individual events, newest first. Always excludes internal `engagement` beacons. Scroll-paginated with the standard `data`/`meta`/`links` envelope — see [Conventions](/api/conventions#paginated-endpoints).

**Query parameters**

| Parameter  | Type   | Required | Description                                                                                                                                                                                                                         |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `range`    | string | No       | Preset date range. See [Conventions](/api/conventions#date-ranges).                                                                                                                                                                 |
| `from`     | string | No       | Custom range start, `Y-m-d`.                                                                                                                                                                                                        |
| `to`       | string | No       | Custom range end, `Y-m-d`.                                                                                                                                                                                                          |
| `types`    | string | No       | Comma-separated list of event types to include, e.g. `outbound,download`. Unknown values are silently dropped. Omit to include every type. Allowed: `pageview`, `event`, `outbound`, `download`, `button`, `form`, `copy`, `error`. |
| `per_page` | int    | No       | Page size, 1–100. Default 50.                                                                                                                                                                                                       |

Filter dimensions (`path`, `country`, `browser`, `prop_key`/`prop_value`, etc.) are also accepted — see [Conventions](/api/conventions#filters).

**Response** — each item in `data`:

| Field          | Type              | Description                                                                                                                                                    |
| -------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_type`   | string            | One of the types listed above.                                                                                                                                 |
| `event_name`   | string            | Custom event name, autocapture kind, or error name. Empty for `pageview`.                                                                                      |
| `timestamp`    | string (ISO 8601) | When the event was recorded.                                                                                                                                   |
| `path`         | string            | Page path.                                                                                                                                                     |
| `url`          | string            | Full page URL.                                                                                                                                                 |
| `title`        | string            | Page title.                                                                                                                                                    |
| `hostname`     | string            | Page hostname.                                                                                                                                                 |
| `user_id`      | string            | Identified user id; empty for an anonymous visitor.                                                                                                            |
| `visitor_id`   | string (uuid)     | Anonymous visitor id.                                                                                                                                          |
| `display_name` | string            | Generated display nickname for the visitor/user.                                                                                                               |
| `avatar_url`   | string            | Generated avatar URL for the visitor/user.                                                                                                                     |
| `country`      | string            | Visitor's country.                                                                                                                                             |
| `device`       | string            | Device type.                                                                                                                                                   |
| `browser`      | string            | Browser name.                                                                                                                                                  |
| `os`           | string            | Operating system.                                                                                                                                              |
| `properties`   | object            | The event's custom properties, string ⇒ string.                                                                                                                |
| `error_id`     | string \| null    | The error's fingerprint id (same `id` a `/stats/errors` row carries) when `event_type` is `error`; `null` otherwise. Link this to `GET /stats/errors/{error}`. |

Status: `200 OK`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/stats/events?range=last_7_days&types=outbound,download" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  await fetch('https://clickbase.so/api/sites/example.com/stats/events?range=last_7_days&types=outbound,download', {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  });
  ```

  ```python title="Python" theme={null}
  requests.get(
      'https://clickbase.so/api/sites/example.com/stats/events',
      params={'range': 'last_7_days', 'types': 'outbound,download'},
      headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
  )
  ```
</CodeGroup>

### Events timeseries

```http theme={null}
GET /api/sites/{siteKey}/stats/events/timeseries
```

Per-bucket event counts, one series per event type present — the Events explorer chart. Always excludes `engagement`.

**Query parameters**

| Parameter | Type   | Required | Description                                                                                                     |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `range`   | string | No       | Preset date range.                                                                                              |
| `from`    | string | No       | Custom range start, `Y-m-d`.                                                                                    |
| `to`      | string | No       | Custom range end, `Y-m-d`.                                                                                      |
| `types`   | string | No       | Comma-separated subset of event types to chart (same allowlist as the list endpoint). Omit to chart every type. |

Filter dimensions are also accepted.

**Response** — flat object:

| Field    | Type                 | Description                                                                |
| -------- | -------------------- | -------------------------------------------------------------------------- |
| `labels` | string\[] (ISO 8601) | Bucket start timestamps.                                                   |
| `types`  | string\[]            | Event types present in `series` (the requested subset, or all list types). |
| `series` | object               | Map of event type ⇒ `int[]` counts, index-aligned with `labels`.           |
| `group`  | string               | Resolved bucket size: `hour`, `day`, `week`, or `month`.                   |

Status: `200 OK`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/stats/events/timeseries?range=last_7_days" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  await fetch('https://clickbase.so/api/sites/example.com/stats/events/timeseries?range=last_7_days', {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  });
  ```

  ```python title="Python" theme={null}
  requests.get(
      'https://clickbase.so/api/sites/example.com/stats/events/timeseries',
      params={'range': 'last_7_days'},
      headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
  )
  ```
</CodeGroup>

### Event property breakdown

```http theme={null}
GET /api/sites/{siteKey}/stats/events/property-breakdown
```

The per-event drill-down: the top custom-property key/value pairs recorded for one exact `event_name` within one `event_type`, ranked by unique visitors. There is no site-level property allow-list — any key the matching events actually carried is returned. Capped at 50 rows.

**Query parameters**

| Parameter    | Type   | Required | Description                                                                                                      |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `range`      | string | No       | Preset date range.                                                                                               |
| `from`       | string | No       | Custom range start, `Y-m-d`.                                                                                     |
| `to`         | string | No       | Custom range end, `Y-m-d`.                                                                                       |
| `event_type` | string | Yes      | One of `event`, `outbound`, `download`, `button`, `form`, `copy`, `error`. Note `pageview` is not breakdownable. |
| `event_name` | string | Yes      | Exact event name to drill into. Max 255 chars.                                                                   |

Filter dimensions are also accepted.

**Response** — flat object:

| Field             | Type      | Description                                       |
| ----------------- | --------- | ------------------------------------------------- |
| `rows`            | object\[] | Up to 50 ranked key/value pairs.                  |
| `rows[].key`      | string    | Property key.                                     |
| `rows[].value`    | string    | Property value.                                   |
| `rows[].visitors` | int       | Unique visitors that carried this key/value pair. |

Status: `200 OK`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/stats/events/property-breakdown?event_type=button&event_name=Signup+Click&range=last_7_days" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  const params = new URLSearchParams({ event_type: 'button', event_name: 'Signup Click', range: 'last_7_days' });
  await fetch(`https://clickbase.so/api/sites/example.com/stats/events/property-breakdown?${params}`, {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  });
  ```

  ```python title="Python" theme={null}
  requests.get(
      'https://clickbase.so/api/sites/example.com/stats/events/property-breakdown',
      params={'event_type': 'button', 'event_name': 'Signup Click', 'range': 'last_7_days'},
      headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
  )
  ```
</CodeGroup>

### List page titles

```http theme={null}
GET /api/sites/{siteKey}/stats/page-titles
```

Document titles ranked by sessions, with pageviews, bounce rate, dwell time, and the session-count change versus the previous period. Scroll-paginated with the standard `data`/`meta`/`links` envelope.

**Query parameters**

| Parameter  | Type   | Required | Description                   |
| ---------- | ------ | -------- | ----------------------------- |
| `range`    | string | No       | Preset date range.            |
| `from`     | string | No       | Custom range start, `Y-m-d`.  |
| `to`       | string | No       | Custom range end, `Y-m-d`.    |
| `per_page` | int    | No       | Page size, 1–100. Default 25. |

Filter dimensions are also accepted.

**Response** — each item in `data`:

| Field                  | Type          | Description                                                                                           |
| ---------------------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `title`                | string        | Document title.                                                                                       |
| `path`                 | string        | The title's most recently seen page path.                                                             |
| `hostname`             | string        | The title's most recently seen hostname.                                                              |
| `pageviews`            | int           | Total pageviews for this title in range.                                                              |
| `sessions`             | int           | Unique sessions that viewed this title.                                                               |
| `bounce_rate`          | float         | Percentage (0–100) of those sessions that had exactly one pageview.                                   |
| `time_on_page_seconds` | float \| null | Average engaged time on the title, in seconds; `null` when no engagement data.                        |
| `sessions_previous`    | int           | Sessions for this title in the equivalent previous period.                                            |
| `sessions_change_pct`  | float \| null | Percent change vs. `sessions_previous`; `null` when there is no previous baseline to compare against. |

Status: `200 OK`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/stats/page-titles?range=last_7_days" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  await fetch('https://clickbase.so/api/sites/example.com/stats/page-titles?range=last_7_days', {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  });
  ```

  ```python title="Python" theme={null}
  requests.get(
      'https://clickbase.so/api/sites/example.com/stats/page-titles',
      params={'range': 'last_7_days'},
      headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
  )
  ```
</CodeGroup>

### Page title timeseries

```http theme={null}
GET /api/sites/{siteKey}/stats/page-titles/timeseries
```

Bucketed unique-session counts for one document title — the Pages table sparkline.

**Query parameters**

| Parameter | Type   | Required | Description                           |
| --------- | ------ | -------- | ------------------------------------- |
| `title`   | string | Yes      | Exact document title. Max 2048 chars. |
| `range`   | string | No       | Preset date range.                    |
| `from`    | string | No       | Custom range start, `Y-m-d`.          |
| `to`      | string | No       | Custom range end, `Y-m-d`.            |

Filter dimensions are also accepted.

**Response** — flat object:

| Field    | Type                 | Description                                              |
| -------- | -------------------- | -------------------------------------------------------- |
| `labels` | string\[] (ISO 8601) | Bucket start timestamps.                                 |
| `values` | int\[]               | Unique sessions per bucket, index-aligned with `labels`. |
| `group`  | string               | Resolved bucket size: `hour`, `day`, `week`, or `month`. |

Status: `200 OK`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/stats/page-titles/timeseries?title=Pricing&range=last_7_days" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  const params = new URLSearchParams({ title: 'Pricing', range: 'last_7_days' });
  await fetch(`https://clickbase.so/api/sites/example.com/stats/page-titles/timeseries?${params}`, {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  });
  ```

  ```python title="Python" theme={null}
  requests.get(
      'https://clickbase.so/api/sites/example.com/stats/page-titles/timeseries',
      params={'title': 'Pricing', 'range': 'last_7_days'},
      headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
  )
  ```
</CodeGroup>

### Filter value suggestions

```http theme={null}
GET /api/sites/{siteKey}/stats/filter-values
```

Autocomplete for the Filter popover: distinct values seen for one dimension over the resolved range/filters, ranked by count. The requested dimension's own active filter is stripped before suggesting (so alternatives still show); other active filters continue to narrow the suggestions.

**Query parameters**

| Parameter   | Type   | Required | Description                                                                                                                                                                                                                                                                                                                                                                |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dimension` | string | Yes      | One of `path`, `entry_path`, `title`, `hostname`, `user_id`, `event_name`, `visit_count`, `referrer`, `channel`, `source`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `browser`, `os`, `size`, `country`, `region`, `city`. Note `campaign`, `goal`, and `prop_key`/`prop_value` — filterable elsewhere — are not suggestible dimensions here. |
| `range`     | string | No       | Preset date range.                                                                                                                                                                                                                                                                                                                                                         |
| `from`      | string | No       | Custom range start, `Y-m-d`.                                                                                                                                                                                                                                                                                                                                               |
| `to`        | string | No       | Custom range end, `Y-m-d`.                                                                                                                                                                                                                                                                                                                                                 |
| `limit`     | int    | No       | Max suggestions, 1–1000. Default 1000.                                                                                                                                                                                                                                                                                                                                     |

Other filter dimensions (besides `dimension` itself) are also accepted, to narrow suggestions.

**Response** — flat object:

| Field            | Type      | Description                                        |
| ---------------- | --------- | -------------------------------------------------- |
| `values`         | object\[] | Ranked distinct values for the dimension.          |
| `values[].value` | string    | The raw value.                                     |
| `values[].label` | string    | Display label (currently always equal to `value`). |

Status: `200 OK`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/stats/filter-values?dimension=country&range=last_7_days" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  const params = new URLSearchParams({ dimension: 'country', range: 'last_7_days' });
  await fetch(`https://clickbase.so/api/sites/example.com/stats/filter-values?${params}`, {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  });
  ```

  ```python title="Python" theme={null}
  requests.get(
      'https://clickbase.so/api/sites/example.com/stats/filter-values',
      params={'dimension': 'country', 'range': 'last_7_days'},
      headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
  )
  ```
</CodeGroup>