Verdicts & scoring

Every Foil session produces a verdict (human, bot, or inconclusive) and a risk score (integer 0 – 100). Your backend uses the verdict to decide what to do.

Verdicts

Verdict	Typical risk score	Meaning	Suggested action
`human`	Below 40	No evidence of automation	Allow
`inconclusive`	40 – 69	Not enough evidence for a confident call	Challenge or gather more context
`bot`	70 – 100	Automated or non-human behavior detected	Block or rate-limit

The score ranges are typical, not a fixed mapping. Foil decides the verdict from the score together with the evidence behind it:

Definitive evidence of automation produces bot, whatever else the session shows.
A score of 70 or higher becomes bot only when deterministic evidence corroborates it. Behavioral evidence alone never produces bot, so a high score without corroboration gives inconclusive.
In the snapshot phase, a score below 40 gives human. After the snapshot phase, a score below 40 gives human only when the session has enough behavioral evidence, and otherwise gives inconclusive.

Branch on verdict, not on the score.

Risk score

The risk score is an integer from 0 to 100. A higher score means stronger evidence of automation. Foil combines the evidence from each detection category and normalizes the result with a sigmoid function. Branch your policy on the verdict:

if verdict == "bot"          → block or rate-limit
if verdict == "inconclusive" → challenge
if verdict == "human"        → allow

Use the score to triage sessions within a verdict, not to override it. For example, review the highest-scoring inconclusive sessions first, or treat a bot verdict at 71 with more caution than one at 98.

Evaluation phases

Foil evaluates sessions in two phases:

Phase	When	What it uses	Confidence
`snapshot`	Immediately on session creation	Environment probes, fingerprint, anti-tamper	Good for deterministic signals
`behavioral`	After user interaction	Mouse, keyboard, touch, timing patterns	Higher confidence for ambiguous cases

If you call getSession() before the user interacts with the page, you get a snapshot-phase result, which is provisional. A session that shows no sign of automation typically receives human. For the highest confidence, call getSession() after the user has interacted with the page for at least a few seconds, so that the result includes behavioral evidence.

Preliminary vs final

Status	Meaning
`preliminary`	Early result, may be updated as more data arrives
`final`	Complete evaluation, won’t change

Snapshot-phase results are always preliminary. Behavioral-phase results are always final.

Attribution

When Foil can tell what is behind a session, the session includes attribution: a list of labels and a list of behaviors. Attribution helps you log and review sessions. Use verdict to decide whether to allow, challenge, or block. Each label has a kind, a machine-readable value, and a confidence.

Kind	What it describes	Example values
`actor`	The type of client	`automation`, `ai-agent`, `crawler`, `unknown`
`tool`	The automation framework	`playwright`, `puppeteer`, `selenium`
`provider`	The service that hosts the browser, when Foil recognizes it	Varies
`product`	The specific agent or product	Varies
`organization`	The organization that operates the client, when known	Varies
`purpose`	Why the client is on your site	`search-engine`, `ai-search`, `ai-data-scraper`
`environment`	The browser engine or how the browser is delivered	`chromium`, `firefox`, `webkit`, `headless`, `cloud`, `mobile-device-farm`
`trust`	Whether the client’s claimed identity holds up	`verified`, `fabricated`, `spoofed-identity`
`evasion`	An attempt to hide automation	`stealth`, `webdriver-masking`

Behaviors describe how the session produced input. Each behavior has a channel (typing, form, mouse, touch, scroll, or clipboard), a value such as synthetic-typing or natural-mouse, and a confidence. The two places that return attribution use slightly different shapes:

The session detail endpoint (GET /v1/sessions/:id) returns attribution with a label display string on each entry and confidence as an integer from 0 to 100.
The sealed token returns attribution.bot with the same labels and behaviors lists, but its entries have no label string, and confidence is a number from 0 to 1.

{
  "attribution": {
    "bot": {
      "labels": [
        { "kind": "actor", "value": "automation", "confidence": 0.97 },
        { "kind": "tool", "value": "playwright", "confidence": 0.92 },
        { "kind": "evasion", "value": "stealth", "confidence": 0.81 }
      ],
      "behaviors": [
        { "channel": "typing", "value": "synthetic-typing", "confidence": 0.88 }
      ]
    }
  }
}

Both attribution (session detail) and attribution.bot (sealed token) are null when Foil has nothing to report, so check for null before you read labels.

Using verdicts in your API

The sealed token returns the Decision shape directly:

{
  "event_id": "evt_7m2k9x4v8q1n5t3w6r0p2c4y8h",
  "verdict": "bot",
  "risk_score": 94,
  "phase": "behavioral",
  "is_provisional": false,
  "manipulation": { "score": 18, "verdict": "low" },
  "evaluation_duration_ms": 33,
  "evaluated_at": "2026-03-17T00:00:03.000Z"
}

event_id is unique to each token, and evaluated_at is the time Foil produced it. manipulation is null when Foil has no manipulation assessment for the session. The session detail endpoint (GET /v1/sessions/:id) renames these fields into a more descriptive, action-oriented vocabulary. (The list endpoint, GET /v1/sessions, keeps the sealed-token names - verdict, phase, is_provisional - in its latest_decision summary.)

Sealed token field	Session API field	Values
`verdict`	`decision.automation_status`	`human` → `human`, `bot` → `automated`, `inconclusive` → `uncertain`
`risk_score`	`decision.risk_score`	`0` – `100` integer (same scale)
`phase`	`decision.evaluation_phase`	`snapshot` or `behavioral` (may be `null` on sessions that haven’t evaluated yet)
`is_provisional`	`decision.decision_status`	`true` → `preliminary`, `false` → `final`

The underlying data is identical - only the field names and the automation_status / decision_status value labels differ. The session detail decision also carries event_id and evaluated_at under the same names, and it doesn’t include manipulation or evaluation_duration_ms.

Policy recommendations

Start with report-only - log verdicts without blocking for the first week
Treat inconclusive as an opportunity - challenge with CAPTCHA or email verification, don’t block
Wait for behavioral phase on high-value actions when possible
Use the score for edge cases - a bot verdict at 71 is weaker than one at 98
Keep your Foil decision in your audit trail - log the verified session_id alongside the business action

What’s next

Detection categories - what signals feed into the score
Server verification - verify handoffs on your backend
Sessions API - full session detail response

Overview

Get started

Integrate

Use cases

Learn

Resources

Verdicts & scoring

Verdicts

Risk score

Evaluation phases

Preliminary vs final

Attribution

Using verdicts in your API

Policy recommendations

What’s next

​Verdicts

​Risk score

​Evaluation phases

​Preliminary vs final

​Attribution

​Using verdicts in your API

​Policy recommendations

​What’s next

Verdicts

Risk score

Evaluation phases

Preliminary vs final

Attribution

Using verdicts in your API

Policy recommendations

What’s next