# Request logs & analytics

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

Sentinel can record the requests made with each API key and aggregates them into hourly statistics. Use the logs to find out why a request was denied or a verification failed, and the statistics to follow traffic, success rates and errors over time.

Logging is off for a key until you turn it on. Searching and reading statistics need an admin session with read access to the `logs` feature of the account (root, or any role that lists `logs`, read-only included).

## Turn logging on

Each API key has a `requestLogging` level. Set it when you create or edit the key, in the admin UI (**API Keys → Request logging**) or with the API. See [Managing API keys](/docs/sentinel/v2/policies/api-keys/#request-logging) for the steps.

| `requestLogging` | Admin UI label | Logged |
| --- | --- | --- |
| `none` (default) | **Off** | Nothing |
| `verification` | **Verification** | `GET`/`POST /v2/challenge` and `POST /v2/verify`. With HIS on, the `GET` redirect isn't logged; the `POST` is. |
| `all` | **All** | Every request authenticated with the key: also detection calls such as `POST /v2/classifier` and, for a `full` key, management calls, as `endpoint: "other"` |

A `public` key only calls the widget endpoints, so `verification` and `all` log the same requests for it. A new level applies from the key's next request; records already written stay.

### What isn't logged

A request is logged only when Sentinel knows which key made it and that key has logging on. So these requests leave no record:

- Rate-limited requests (`429`).
- Authentication failures: a missing, unknown or deleted key, a deleted security group, the wrong auth scheme or secret for the key's access level, or a deleted or suspended account.
- Requests made with a key whose level is `none`, or that its level doesn't cover.

Requests denied by security-group rules (`403 ACCESS_DENIED`), invalid payloads and failed verifications are logged. Statistics count only logged requests, so a key with logging off contributes nothing to them.

## Storage and retention

Sentinel buffers records in memory and writes them in batches, at least every `[request_logs] flush_interval` (default `1s`) or once `[request_logs] batch_size` (default `100`) records are pending. New requests show up in searches within a few seconds, and writing logs never delays a response.

| Store | Raw records (`_search`) | Statistics (`_stats`) |
| --- | --- | --- |
| Main database (default) | `[request_logs] retention`, default `72h`, at least `2h` | Kept indefinitely, as hourly aggregates |
| [ClickHouse](/docs/sentinel/v2/operations/clickhouse/) | `[clickhouse] raw_retention`, default `90d` | 5 years, as hourly aggregates |

In the main database, Sentinel folds each completed UTC hour into hourly aggregates and deletes raw records once they're older than `retention`. `_stats` combines the aggregates with recent raw records, so its results don't change when an hour is compacted. `_search` only finds records still within retention. To estimate how much space the logs take, see [Database size](/docs/sentinel/v2/install/#database-size).

```toml
[request_logs]
retention = "7d"       # raw records in the main database; hourly stats are kept regardless
flush_interval = "1s"
batch_size = 100
```

See [`[request_logs]`](/docs/sentinel/v2/reference/configuration/#request_logs) for the keys and limits.

<Callout type="warning" title="Best-effort, not an audit trail">

If the write queue is full or a batch fails to write, Sentinel drops those records and logs a warning. Don't use request logs for billing or compliance. Dropped records are counted in `altcha_sentinel_request_logs_dropped_total` and reported by the `system.request_logs` doctor check; see [Monitoring & metrics](/docs/sentinel/v2/operations/monitoring/).

## Log record fields

Every record has every field below; a field with no value is `null`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | `log_…`, ascending with time |
| `time` | string | When Sentinel received the request, RFC 3339 UTC |
| `accountId` | string | The key's account |
| `apiKeyId` | string \| null | The key. `null` unless the caller can also read the account's `api_keys` feature (root always can). |
| `endpoint` | string | `challenge`, `verify`, or `other` |
| `method` | string | HTTP method |
| `path` | string | URL path without the query string, cut to 200 characters |
| `statusCode` | number | Response status. A failed verification is a `200` too; check `verified`. |
| `latencyMs` | number | Server handling time in milliseconds, without network time |
| `ip` | string \| null | Client IP, anonymized with `[privacy] anonymize_ip` |
| `userIp` | null | Reserved; always `null` in this version |
| `referrer` | string \| null | Lower-cased host of `Origin`, or of `Referer` when `Origin` is missing, without scheme, port or path |
| `countryCode` | string \| null | Lower-case country code: for verifications, from the time zone the widget sent; otherwise from [IP geolocation](/docs/sentinel/v2/reference/configuration/#ip_resolver) when configured |
| `browser` | string \| null | Browser family from `User-Agent`: `chrome`, `firefox`, `edge`, `safari`, `brave`, `vivaldi`, `opera` or `app` |
| `device` | string \| null | `desktop`, `mobile`, `tablet`, `console`, `smarttv`, `wearable`, `embedded` or `bot` |
| `network` | string \| null | Network type from IP geolocation or `tor`/`proxy` threat lists: `tor`, `proxy`, `hosting`, `mobile` or `fixed` |
| `powAlgorithm` | string \| null | Challenges: the proof-of-work algorithm issued, e.g. `PBKDF2/SHA-256` |
| `protectionLevel` | string \| null | Challenges: `frictionless` or `code_challenge` |
| `verified` | boolean \| null | Verifications: the outcome. `null` when the payload couldn't be decoded or the request was denied first. |
| `verificationId` | string \| null | Verifications: the challenge `id` (or nonce), cut to 100 characters |
| `error` | string \| null | A failed verification's `reason` (e.g. `CHALLENGE_ALREADY_USED`, `INVALID_SOLUTION`), or an error response's `code` (e.g. `ACCESS_DENIED`); see [Error codes](/docs/sentinel/v2/reference/errors/) |
| `context` | object \| null | Labels: `agent` (Web Bot Auth result), `rules` (live security-group rules that matched or decided, comma-separated), `monitor` (monitored rules that would have acted), `threats` (names of the threat sources matching the client IP, `manual` and `auto` for entries, comma-separated) and `threatAction` (the IP's threat verdict, when a match has an action). Private IPs have no threat labels, and other [non-routable IPs](/docs/sentinel/v2/features/threat-intelligence/#private-and-non-routable-ips) only those of manual entries. Absent keys aren't set. |
| `triggeredRules` | string[] \| null | Rules that scored above 0. `POST /v2/verify` and `POST /v2/classifier`: the classification rules, highest first. `POST /v2/eml`: the response's `triggeredRules` (the EML rules, highest first, including `CLASSIFICATION` when it scored), then its `classification.triggeredRules`. `null` when none triggered. |
| `hisAutomation` | number \| null | HIS bot probability (0.01–1) on `POST /v2/challenge` with HIS on, and on code-challenge verifications that collected HIS data |
| `hisAssistive` | boolean \| null | With `hisAutomation`: whether the interaction was keyboard-only or assistive-technology driven |

Rules appear in `context.rules` and `context.monitor` by `name`, or `#` and their index when unnamed. Name your [security rules](/docs/sentinel/v2/policies/security-rules/) so the labels stay meaningful when rules are reordered.

## Search logs

`POST /v2/request-logs/_search` returns raw records, filtered and paged. `filter.accountId` is required; every other filter is optional and all must match.

```bash
curl https://sentinel.example.com/v2/request-logs/_search \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{
"filter": {"accountId": "acc_…", "endpoint": "verify", "from": "2026-11-19T00:00:00Z"},
"sortBy": "time",
"sortDir": "desc",
"limit": 2
}'
```

```json
{
"data": [
{
  "id": "log_1k7pi2f8d0062j3cp74",
  "time": "2026-11-19T09:26:44.237000+00:00",
  "accountId": "acc_1k7pi0dp20011crb5ea",
  "apiKeyId": "key_1k7pi1ea90061n8o2jd",
  "endpoint": "verify",
  "method": "POST",
  "path": "/v2/verify",
  "statusCode": 400,
  "latencyMs": 0.258,
  "ip": "203.0.113.7",
  "referrer": "shop.example.com",
  "browser": "chrome",
  "device": "desktop",
  "verified": null,
  "error": "INVALID_PAYLOAD",
  …
},
{
  "id": "log_1k7pi2f8a004020r02e",
  "time": "2026-11-19T09:26:44.234000+00:00",
  "endpoint": "verify",
  "statusCode": 200,
  "countryCode": "cz",
  "verified": false,
  "verificationId": "cd1bce52b2f227570f557881c7bf6a75",
  "error": "CHALLENGE_ALREADY_USED",
  …
}
],
"pagination": { "limit": 2, "offset": 0, "total": 3 }
}
```

| Filter | Matches |
| --- | --- |
| `accountId` | **Required.** Records of this account |
| `apiKeyId` | Records of this key |
| `securityGroupId` | Records of the keys currently in this group, deleted keys included |
| `from` / `to` | `time` at or after `from`, and strictly before `to` (RFC 3339) |
| `endpoint` | `challenge`, `verify` or `other` |
| `path` | Exact stored `path`, e.g. `/v2/classifier` |
| `statusCode` | An exact status (`403`) or a class (`"4xx"`) |
| `verified` | `true` or `false` |
| `ip` | Exact stored `ip`; with anonymization on, search for the anonymized address |
| `protectionLevel` | `frictionless` or `code_challenge` |
| `rule` / `monitorRule` | Records whose `context.rules` / `context.monitor` lists this rule name or `#index` |

Sort with `sortBy` (`time`, `statusCode` or `latency`) and `sortDir` (`asc`, the default, or `desc`). Page with `limit` (1–200, default `100`) and `offset`. `pagination.total` counts every match. When you page through a live range, fix `to` at the time of the first page so new records don't shift the pages.

See the [API reference](/sentinel-api-docs-v2.html#tag/request-logs/POST/v2/request-logs/_search) for the full schema.

## Read statistics

`POST /v2/request-logs/_stats` returns totals, a time series and top-value breakdowns for a range. `accountId`, `from` and `to` are required; `apiKeyId` and `securityGroupId` narrow it like the search filters.

```bash
curl https://sentinel.example.com/v2/request-logs/_stats \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "acc_…",
"from": "2026-11-19T00:00:00+01:00",
"to": "2026-11-20T00:00:00+01:00",
"interval": "day",
"timeZone": "Europe/Prague",
"top": 3
}'
```

```json
{
"data": {
"interval": "day",
"timeZone": "Europe/Prague",
"from": "2026-11-19T00:00:00+01:00",
"to": "2026-11-20T00:00:00+01:00",
"totals": {
  "requests": 6,
  "challenges": 3,
  "verifications": 3,
  "verified": 1,
  "failed": 1,
  "errors4xx": 1,
  "errors5xx": 0,
  "latencyAvgMs": 29.303,
  "protectionLevels": { "frictionless": 3 },
  "hisCount": 0,
  "hisAutomationAvg": null,
  …
},
"series": [
  { "time": "2026-11-19T00:00:00+01:00", "requests": 6, "challenges": 3, … }
],
"breakdowns": {
  "endpoint": [ { "value": "challenge", "count": 3 }, { "value": "verify", "count": 3 } ],
  "error": [
    { "value": "CHALLENGE_ALREADY_USED", "count": 1 },
    { "value": "INVALID_PAYLOAD", "count": 1 }
  ],
  "referrer": [ { "value": "shop.example.com", "count": 6 } ],
  "statusCode": [ { "value": 200, "count": 5 }, { "value": 400, "count": 1 } ],
  "verified": [ { "value": false, "count": 1 }, { "value": true, "count": 1 } ],
  …
}
}
}
```

- **Interval.** `hour` (UTC hours) or `day` (local calendar days in `timeZone`). The default is `hour` for ranges under 6 days and `day` otherwise. A range is at most 366 days, and at most 31 days with `hour`.
- **Bucket rounding.** Sentinel widens the range to whole buckets; the response's `from` and `to` show the widened range. `series` lists every bucket, empty ones included.
- **Totals.** `verified` and `failed` count verification outcomes; a verification rejected with a 4xx before the solution was checked is in neither. A failed verification is a `200`, so it isn't in `errors4xx`. `latencyAvgMs` and `hisAutomationAvg` are `null` when nothing was counted.
- **Breakdowns.** Each lists the `top` (1–100, default `10`) most frequent values for `apiKey`, `endpoint`, `statusCode`, `verified`, `error`, `protectionLevel`, `powAlgorithm`, `referrer`, `countryCode`, `browser`, `device`, `network`, `triggeredRules` (classifier and EML rules), `rules` and `monitor`, as `{value, count}`. `apiKey` is `[]` unless the caller can read the account's `api_keys` feature.

The verification success rate is `verified / (verified + failed)`, and the error rate `(errors4xx + errors5xx) / requests`. To see the requests behind a number, search with the same account, key and range, for example with `"statusCode": "4xx"`. Unknown account or key IDs return zeros.

See the [API reference](/sentinel-api-docs-v2.html#tag/request-logs/POST/v2/request-logs/_stats) for every field.

Both endpoints return `400 VALIDATION_ERROR` for a malformed body or range (for example `to must be after from`) and `403 PERMISSION_REQUIRED` without `logs` access to the account. See [Error codes](/docs/sentinel/v2/reference/errors/).

## In the admin UI

- **Dashboard** shows the statistics for the selected account: pick a period (**Today**, **Last 7 days**, **Custom range**, …) and optionally an API key.
- **Logs** lists the raw records, newest first. Filter by **API key**, **Security group**, **From**/**To**, **Endpoint** (`challenge`, `verify`, `other`, or a typed path), **Status**, **Result**, **Protection level**, **IP address**, **Security rule** or **Monitored rule**. Open a record with **View details**, or export the results as CSV or JSON.

Both pages show only requests of keys with logging on. When a key has logging off, the API key form warns that the dashboard will show no data for it.

## Privacy

Request logs store client IPs, referrer hosts and browser details. With `[privacy] anonymize_ip = true`, Sentinel zeroes the last part of public client IPs before they're stored; records written earlier keep the full address. Shorten `[request_logs] retention` (or `[clickhouse] raw_retention`) to keep raw records for less time; the hourly statistics hold no IPs. See [Privacy & data handling](/docs/sentinel/v2/security/privacy/).

## Related

- [Managing API keys](/docs/sentinel/v2/policies/api-keys/)
- [ClickHouse](/docs/sentinel/v2/operations/clickhouse/)
- [Configuration reference: `[request_logs]`](/docs/sentinel/v2/reference/configuration/#request_logs)
- [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/)
- [Security rules](/docs/sentinel/v2/policies/security-rules/)
- [Monitoring & metrics](/docs/sentinel/v2/operations/monitoring/)
- [Privacy & data handling](/docs/sentinel/v2/security/privacy/)
