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

# Error tracking

> The Errors report: distinct JavaScript error messages ranked by occurrence, a single error's detail, its chart, and its individual occurrences.

The Errors report: distinct JavaScript error messages ranked by occurrence, a single error's detail, its chart, and its individual occurrences. Rows in the [Events log](/api/events) carry an `error_id` — the same fingerprint id used here — so an `error` event links straight into this report.

An error is addressed by `{error}`, its deterministic **fingerprint** (a UUID derived from the site and the exact error message; the `id` field returned by the endpoints below). Fingerprint resolution is range-independent — a known fingerprint always resolves, even for a range with zero matching occurrences — but a fingerprint that has never belonged to the site returns `404 Not Found`, so one team can never probe another's errors.

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 error names

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

Distinct error messages ranked by occurrence count over the resolved range, with session counts. 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.            |
| `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 20. |

Filter dimensions are also accepted.

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

| Field         | Type          | Description                                                                     |
| ------------- | ------------- | ------------------------------------------------------------------------------- |
| `id`          | string (uuid) | Deterministic fingerprint for this error message. Use with the endpoints below. |
| `message`     | string        | The error message.                                                              |
| `error_name`  | string        | The error's name/type (e.g. `TypeError`); `Error` when none was captured.       |
| `occurrences` | int           | Total occurrences in range.                                                     |
| `sessions`    | int           | Unique sessions that hit this error.                                            |

Status: `200 OK`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/stats/errors?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/errors?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/errors',
      params={'range': 'last_7_days'},
      headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
  )
  ```
</CodeGroup>

### Get an error

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

A single error group's summary over the resolved range/filters.

**Path parameters**

| Parameter | Type          | Required | Description                                                                    |
| --------- | ------------- | -------- | ------------------------------------------------------------------------------ |
| `siteKey` | string        | Yes      | Site UUID or domain.                                                           |
| `error`   | string (uuid) | Yes      | Error fingerprint. A malformed, foreign, or unknown fingerprint returns `404`. |

**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`.   |

Filter dimensions are also accepted. A recognized fingerprint outside the requested range/filters still returns `200 OK` with `occurrences`/`sessions` at `0`, not `404` — only an unknown fingerprint 404s.

**Response** — flat object:

| Field         | Type          | Description                                                            |
| ------------- | ------------- | ---------------------------------------------------------------------- |
| `id`          | string (uuid) | The requested fingerprint, echoed back.                                |
| `message`     | string        | The error message.                                                     |
| `error_name`  | string        | The error's name/type; `Error` when none was captured.                 |
| `occurrences` | int           | Occurrences within the resolved range/filters.                         |
| `sessions`    | int           | Unique sessions that hit this error within the resolved range/filters. |

Status: `200 OK` (`404` for an unknown fingerprint).

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/stats/errors/{error}?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/errors/${error}?range=last_7_days`, {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  });
  ```

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

### Error timeseries

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

Per-bucket occurrence counts for one error — the "Errors over time" chart on the error's detail page.

**Path parameters**

| Parameter | Type          | Required | Description                                              |
| --------- | ------------- | -------- | -------------------------------------------------------- |
| `siteKey` | string        | Yes      | Site UUID or domain.                                     |
| `error`   | string (uuid) | Yes      | Error fingerprint. An unknown fingerprint returns `404`. |

**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`.   |

Filter dimensions are also accepted.

**Response** — flat object:

| Field    | Type                 | Description                                                            |
| -------- | -------------------- | ---------------------------------------------------------------------- |
| `labels` | string\[] (ISO 8601) | Bucket start timestamps.                                               |
| `types`  | string\[]            | Always `["error"]`.                                                    |
| `series` | object               | `{ "error": int[] }` — occurrence counts, index-aligned with `labels`. |
| `group`  | string               | Resolved bucket size: `hour`, `day`, `week`, or `month`.               |

Status: `200 OK` (`404` for an unknown fingerprint).

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/stats/errors/{error}/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/errors/${error}/timeseries?range=last_7_days`, {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  });
  ```

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

### List error events

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

Individual occurrences of one error, newest first, with the full stack detail. Scroll-paginated with the standard `data`/`meta`/`links` envelope.

**Path parameters**

| Parameter | Type          | Required | Description                                              |
| --------- | ------------- | -------- | -------------------------------------------------------- |
| `siteKey` | string        | Yes      | Site UUID or domain.                                     |
| `error`   | string (uuid) | Yes      | Error fingerprint. An unknown fingerprint returns `404`. |

**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 20. |

Filter dimensions are also accepted.

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

| Field           | Type              | Description                                            |
| --------------- | ----------------- | ------------------------------------------------------ |
| `event_name`    | string            | The error's name/type; `Error` when none was captured. |
| `timestamp`     | string (ISO 8601) | When the error 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.                                      |
| `message`       | string            | The error message.                                     |
| `stack`         | string            | Captured stack trace.                                  |
| `file_name`     | string            | Source file the error was thrown from.                 |
| `line_number`   | string            | Source line number.                                    |
| `column_number` | string            | Source column number.                                  |

Status: `200 OK` (`404` for an unknown fingerprint).

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/stats/errors/{error}/events?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/errors/${error}/events?range=last_7_days`, {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  });
  ```

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