> ## 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](https://docs.clickbase.so/api/events.md) 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](https://docs.clickbase.so/api/conventions.md).

### 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](https://docs.clickbase.so/api/conventions.md#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`.

```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'},
)
```

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

```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'},
)
```

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

```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'},
)
```

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

```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'},
)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.