Signals & fields

The composable signal fields exposed on a scored session — what they mean, their types, and which are usable in custom rules.

A scored session exposes a vocabulary of signal fields. They surface in the verdict response (where applicable) and are the fields you compose rules over. The vocabulary tracks well-known bot-management mental models so they port cleanly.

Adding a field is always additive — existing rules keep working when new signals ship.

Field reference

Field	Type	Source	Rule-usable	Notes
`score`	int `0` or `1`–`99`	combiner	✅	`0` = not computed (sentinel), never the same as `1`
`band`	enum	banding	✅	`not_computed \| definite \| likely_automated \| likely_human \| verified`
`verified_bot`	bool	verified-bot match	✅	True only on real verification — never a UA claim alone
`verified_bot_category`	string \| null	verified-bot match	✅	e.g. `Search`, `AI Crawler`, `AI Search`
`detection_ids`	int[]	engines	✅ (`in` / `not in`)	Stable IDs from the detection registry
`js_detection.passed`	bool \| null	JS-detection engine	✅	Non-enforcing — a `false` never alone forces a bot verdict
`static_resource`	bool	request classification	✅	Asset / extension / `.well-known` detection
`behavioral.mouse_entropy`	float `0`–`1`	behavioral engine	✅	Randomness of pointer movement; humans trend high
`behavioral.scroll_velocity`	float (px/s)	behavioral engine	✅	Scroll speed profile
`behavioral.visibility_changes`	int	behavioral engine	✅	Tab/visibility transitions observed
`behavioral.first_input_delay_ms`	int	behavioral engine	✅	Time to first genuine interaction
`path`	string	request context	✅	Request path, e.g. `/login`
`ip`	string	request context	✅	Request IP
`country`	string	request context	✅	ISO country code
`ua`	string	request context	✅	User-agent string
`session_token`	string	server-minted	❌	Identifier, not a scoring input
`ja4`	string \| null	trusted edge header	✅ (v2)	Null in v1 — no v1 engine reads it yet

The behavioral signals

The behavioral.* aggregates are Botect's core differentiator — they describe how a session interacts, which is far harder to spoof than headers or user-agent strings. They're the fields you'll most often build rules over:

mouse_entropy — humans move pointers in noisy, non-linear paths (high entropy); scripted clicks are jumpy or perfectly straight (low entropy).
scroll_velocity — natural scrolling has variable, decaying velocity; automation tends toward uniform or instantaneous jumps.
visibility_changes — real users switch tabs and windows; many bots never do.
first_input_delay_ms — humans take time to orient before acting; automation often fires immediately.

Behavioral signals accumulate as a session sends more events. A session with very few events may not yet have enough behavioral evidence to leave the not_computed band.

Privacy

Ingest stores no PII. Event payloads are whitelisted per event type to aggregates only (entropy, velocities, counts, timings) — raw inputs, content, and identifying data are rejected at the door with a 422. See Ingest events.

Page identity. The collector reports which page it ran on as a hash plus a normalized template, never a readable URL:

page_path_hash — a 16-character hash of the path. Identical paths hash identically, so repeat visits and sequential crawls are still detectable.
page_path_shape — the path with identifiers masked, so /orders/48812 and /orders/50193 both become /orders/{n}.

The query string and fragment are never collected, so tokens and email addresses in a URL never leave the browser.

Logged-in visitors. If you tell Botect that a session has authenticated in your application, we store a timestamp and nothing else. That endpoint accepts no request body and no query string at all, so a user id or email cannot reach it even by mistake — Botect learns that a session signed in, never who did. Neither field is rule-usable; use the path field (supplied by your own edge at verdict time) to write path rules.

Was this page helpful?