Request logs & analytics
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 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 | [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.
[request_logs]
retention = "7d" # raw records in the main database; hourly stats are kept regardless
flush_interval = "1s"
batch_size = 100See [request_logs] for the keys and limits.
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 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 |
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 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 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.
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
}'{
"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 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.
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
}'{
"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) orday(local calendar days intimeZone). The default ishourfor ranges under 6 days anddayotherwise. A range is at most 366 days, and at most 31 days withhour. - Bucket rounding. Sentinel widens the range to whole buckets; the response's
fromandtoshow the widened range.serieslists every bucket, empty ones included. - Totals.
verifiedandfailedcount verification outcomes; a verification rejected with a 4xx before the solution was checked is in neither. A failed verification is a200, so it isn't inerrors4xx.latencyAvgMsandhisAutomationAvgarenullwhen nothing was counted. - Breakdowns. Each lists the
top(1–100, default10) most frequent values forapiKey,endpoint,statusCode,verified,error,protectionLevel,powAlgorithm,referrer,countryCode,browser,device,network,triggeredRules(classifier and EML rules),rulesandmonitor, as{value, count}.apiKeyis[]unless the caller can read the account'sapi_keysfeature.
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 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.
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.