Skip to main content
ALTCHA®

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.

requestLoggingAdmin UI labelLogged
none (default)OffNothing
verificationVerificationGET/POST /v2/challenge and POST /v2/verify. With HIS on, the GET redirect isn't logged; the POST is.
allAllEvery 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.

StoreRaw records (_search)Statistics (_stats)
Main database (default)[request_logs] retention, default 72h, at least 2hKept indefinitely, as hourly aggregates
ClickHouse[clickhouse] raw_retention, default 90d5 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 = 100

See [request_logs] for the keys and limits.

Log record fields

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

FieldTypeDescription
idstringlog_…, ascending with time
timestringWhen Sentinel received the request, RFC 3339 UTC
accountIdstringThe key's account
apiKeyIdstring | nullThe key. null unless the caller can also read the account's api_keys feature (root always can).
endpointstringchallenge, verify, or other
methodstringHTTP method
pathstringURL path without the query string, cut to 200 characters
statusCodenumberResponse status. A failed verification is a 200 too; check verified.
latencyMsnumberServer handling time in milliseconds, without network time
ipstring | nullClient IP, anonymized with [privacy] anonymize_ip
userIpnullReserved; always null in this version
referrerstring | nullLower-cased host of Origin, or of Referer when Origin is missing, without scheme, port or path
countryCodestring | nullLower-case country code: for verifications, from the time zone the widget sent; otherwise from IP geolocation when configured
browserstring | nullBrowser family from User-Agent: chrome, firefox, edge, safari, brave, vivaldi, opera or app
devicestring | nulldesktop, mobile, tablet, console, smarttv, wearable, embedded or bot
networkstring | nullNetwork type from IP geolocation or tor/proxy threat lists: tor, proxy, hosting, mobile or fixed
powAlgorithmstring | nullChallenges: the proof-of-work algorithm issued, e.g. PBKDF2/SHA-256
protectionLevelstring | nullChallenges: frictionless or code_challenge
verifiedboolean | nullVerifications: the outcome. null when the payload couldn't be decoded or the request was denied first.
verificationIdstring | nullVerifications: the challenge id (or nonce), cut to 100 characters
errorstring | nullA failed verification's reason (e.g. CHALLENGE_ALREADY_USED, INVALID_SOLUTION), or an error response's code (e.g. ACCESS_DENIED); see Error codes
contextobject | nullLabels: 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.
triggeredRulesstring[] | nullRules 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.
hisAutomationnumber | nullHIS bot probability (0.01–1) on POST /v2/challenge with HIS on, and on code-challenge verifications that collected HIS data
hisAssistiveboolean | nullWith 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 }
}
FilterMatches
accountIdRequired. Records of this account
apiKeyIdRecords of this key
securityGroupIdRecords of the keys currently in this group, deleted keys included
from / totime at or after from, and strictly before to (RFC 3339)
endpointchallenge, verify or other
pathExact stored path, e.g. /v2/classifier
statusCodeAn exact status (403) or a class ("4xx")
verifiedtrue or false
ipExact stored ip; with anonymization on, search for the anonymized address
protectionLevelfrictionless or code_challenge
rule / monitorRuleRecords 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) 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 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.

Start typing to search...

↑ ↓ Navigate ↵ Select