Sessions API

Use the Sessions API to retrieve stored result summaries after the browser handoff completes.

Sessions endpoints require a secret key and never return collect-time sealed handoff tokens. Each endpoint also requires a scope on the key: sessions:list, sessions:read, or sessions:update. See Authentication.

Endpoint summary

Method	Path	Purpose
`GET`	`/v1/sessions`	List sessions with the latest result summary. Requires the `sessions:list` scope.
`GET`	`/v1/sessions/:sessionId`	Retrieve deep investigation detail for one session. Requires the `sessions:read` scope.
`PATCH`	`/v1/sessions/:sessionId`	Attach or clear your own end-user ID for one session. Requires the `sessions:update` scope.

`GET /v1/sessions`

Returns one row per session with the latest decision summary. Requires a secret key with the sessions:list scope. The default scopes for a secret key don’t include sessions:list, so add it to keys that list sessions. Supported query parameters:

Parameter	Type	Default	Notes
`limit`	integer	`50`	Page size from `1` to `200`.
`cursor`	string	-	The `pagination.next_cursor` from the previous page.
`verdict`	`bot`, `human`, or `inconclusive`	-	Returns only sessions whose latest decision has this verdict.
`search`	string	-	Matches sessions by ID or request metadata. See the matching rules below.

Rows are ordered by the time of each session’s latest decision, newest first. A limit, verdict, or cursor value that isn’t valid returns 422 with request.validation_failed, and the offset parameter isn’t supported. See Pagination for how to page through results. search matches in one of two ways:

A value that starts with sid_, evt_, or vid_ matches a session ID, event ID, or visitor ID exactly, ignoring case. A 32-character hexadecimal value matches a legacy session ID or event ID exactly.
Any other value is a case-insensitive substring match against the session ID, event ID, visitor ID, client_user_id, page URL, user agent, and IP address.

Example response:

{
  "data": [
    {
      "object": "session",
      "id": "sid_7m2k9x4v8q1n5t3w6r0p2c4y8h",
      "created_at": "2026-03-17T00:00:00.000Z",
      "client_user_id": "user_123",
      "latest_decision": {
        "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"
      },
      "visitor_fingerprint": {
        "object": "visitor_fingerprint",
        "id": "vid_7m2k9x4v8q1n5t3w6r0p2c4y8h",
        "confidence": 93,
        "identified_at": "2026-03-17T00:00:01.000Z"
      }
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": false
  },
  "meta": {
    "request_id": "req_0123456789abcdef0123456789abcdef"
  }
}

In each row, latest_decision carries these fields:

Field	Meaning
`event_id`	The ID of the decision.
`verdict`	`bot`, `human`, or `inconclusive`. Session detail reports the same outcome as `decision.automation_status`: `automated`, `human`, or `uncertain`.
`risk_score`	The risk score, from `0` to `100`.
`phase`	The evaluation phase, `snapshot` or `behavioral`, or `null`.
`is_provisional`	`true` while the decision is preliminary and can still change, and `false` once it is final.
`manipulation`	An object with a `score` and a `verdict` of `none`, `low`, `medium`, or `high`, or `null` when Foil has no manipulation assessment.
`evaluation_duration_ms`	How long the evaluation took, in milliseconds.
`evaluated_at`	When Foil made the decision.

`GET /v1/sessions/:sessionId`

Requires a secret key with the sessions:read scope. A session that doesn’t exist, or that belongs to the other environment, returns 404 with request.not_found. Returns the full public investigation view for one session. The response is intentionally ordered so the most actionable fraud analysis appears first, followed by continuity context, then structured evidence and lower-level telemetry. Unlike GET /v1/sessions, which stays a compact summary surface with latest_decision, session detail uses the richer decision, highlights, signals_fired, and client_telemetry model shown below. Example response:

{
  "data": {
    "object": "session",
    "id": "sid_0123456789abcdefghjkmnpqrs",
    "created_at": "2026-03-24T20:00:00.000Z",
    "client_user_id": "user_123",
    "decision": {
      "event_id": "evt_23456789abcdefghjkmnpqrstv",
      "automation_status": "automated",
      "risk_score": 94,
      "evaluation_phase": "behavioral",
      "decision_status": "final",
      "evaluated_at": "2026-03-24T20:00:05.000Z"
    },
    "highlights": [
      {
        "key": "browser_automation",
        "effect": "increases_risk",
        "importance": "high",
        "summary": "Browser automation markers were detected.",
        "evidence": [
          {
            "signal": "webdriver_detected",
            "name": "WebDriver detected"
          },
          {
            "signal": "anti_detect_browser_indicators",
            "name": "Anti-detect browser indicators"
          }
        ]
      },
      {
        "key": "network_anonymity",
        "effect": "increases_risk",
        "importance": "medium",
        "summary": "This session originated from a VPN-associated network.",
        "evidence": [
          {
            "signal": "vpn_associated_ip",
            "name": "VPN-associated IP"
          }
        ]
      },
      {
        "key": "runtime_anomalies",
        "effect": "increases_risk",
        "importance": "medium",
        "summary": "Runtime integrity checks found suspicious environment traits.",
        "evidence": [
          {
            "signal": "virtualization_indicators",
            "name": "Virtualization indicators"
          },
          {
            "signal": "developer_tools_detected",
            "name": "Developer tools detected"
          },
          {
            "signal": "privacy_hardening_indicators",
            "name": "Privacy hardening indicators"
          }
        ]
      },
      {
        "key": "browser_profile_consistent",
        "effect": "reduces_risk",
        "importance": "medium",
        "summary": "Browser identity and device capabilities are internally consistent for a desktop Chromium environment."
      },
      {
        "key": "known_visitor_fingerprint",
        "effect": "context",
        "importance": "medium",
        "summary": "This visitor fingerprint has been seen before.",
        "evidence": [
          {
            "signal": "returning_visitor_fingerprint",
            "name": "Seen 14 times"
          }
        ]
      }
    ],
    "attribution": {
      "labels": [
        {
          "kind": "actor",
          "value": "automation",
          "label": "Automation",
          "confidence": 97
        },
        {
          "kind": "provider",
          "value": "browserless",
          "label": "Browserless",
          "confidence": 92
        },
        {
          "kind": "tool",
          "value": "playwright",
          "label": "Playwright",
          "confidence": 89
        },
        {
          "kind": "evasion",
          "value": "stealth",
          "label": "Stealth",
          "confidence": 73
        }
      ],
      "behaviors": [
        {
          "channel": "typing",
          "value": "synthetic-typing",
          "label": "Synthetic Typing",
          "confidence": 86
        }
      ]
    },
    "web_bot_auth": {
      "status": "verified",
      "domain": "browserless.io"
    },
    "network": {
      "ip_address": "203.0.113.9",
      "ip_version": "ipv4",
      "status": "ready",
      "summary": "This IP appears associated with VPN traffic.",
      "location": {
        "city": "San Francisco",
        "region": "California",
        "country": "United States",
        "country_code": "US",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "timezone": "America/Los_Angeles",
        "postal_code": "94103",
        "accuracy_radius_km": 10
      },
      "routing": {
        "asn": "64512",
        "organization": "Example Networks"
      },
      "anonymity": {
        "vpn": true,
        "proxy": false,
        "tor": false,
        "relay": false,
        "hosting": false,
        "residential_proxy": false,
        "callback_proxy": false,
        "provider": "Example VPN"
      },
      "reputation": {
        "listed": true,
        "categories": ["vpn"],
        "suspicious_network": false
      },
      "evidence": {
        "risk_signals": ["vpn"],
        "operator_tags": ["vpn"],
        "client_types": ["consumer"],
        "client_count": 3
      },
      "evaluated_at": "2026-03-24T20:00:05.000Z"
    },
    "runtime_integrity": {
      "tampering": "high_risk",
      "developer_tools": "elevated",
      "emulation": "clean",
      "virtualization": "high_risk",
      "privacy_hardening": "notice",
      "identity_spoofing": "clean",
      "replay": "clean",
      "outdated_environment": "clean"
    },
    "native_runtime_integrity": null,
    "native_app": null,
    "native_carrier": null,
    "native_motion_print": null,
    "device_identity": null,
    "install_id": null,
    "visitor_fingerprint": {
      "object": "visitor_fingerprint",
      "id": "vid_456789abcdefghjkmnpqrstvwx",
      "confidence": 93,
      "identified_at": "2026-03-24T20:00:01.000Z",
      "resolution": {
        "method": "fingerprint",
        "basis": "probabilistic"
      },
      "lifecycle": {
        "first_seen_at": "2026-03-01T18:22:11.000Z",
        "last_seen_at": "2026-03-24T20:00:05.000Z",
        "seen_count": 14
      }
    },
    "connection_fingerprint": {
      "ja4": {
        "hash": "t13d1516h2_8daaf6152771_02713d6af862",
        "profile": "chrome",
        "family": "chromium",
        "product": "edge",
        "confidence": "exact",
        "match_source": "full_ja4",
        "deterministic": true,
        "reference": {
          "label": "Edge",
          "source": "master_db",
          "protocol": "t",
          "tls_version": "13",
          "sni": "d",
          "alpn": "h2",
          "cipher_count": {
            "min": 15,
            "max": 16
          },
          "ext_count": {
            "min": 15,
            "max": 16
          },
          "sample_size": 6,
          "verified": true
        }
      },
      "http2": {
        "akamai_fingerprint": "1:65536;4:131072;5:16384|12517377|0|m,p,a,s",
        "profile": "chrome"
      },
      "user_agent_alignment": "match"
    },
    "previous_decisions": [
      {
        "event_id": "evt_3456789abcdefghjkmnpqrstvw",
        "automation_status": "uncertain",
        "risk_score": 41,
        "evaluation_phase": "snapshot",
        "decision_status": "preliminary",
        "evaluated_at": "2026-03-24T20:00:01.000Z"
      }
    ],
    "request": {
      "url": "https://example.com/signup",
      "referrer": "https://example.com/",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.6312.86 Safari/537.36"
    },
    "browser": {
      "name": "Chromium",
      "version": "123.0.0.0",
      "major_version": "123",
      "engine": "blink",
      "app_name": null
    },
    "device": {
      "form_factor": "desktop",
      "operating_system": {
        "name": "macOS",
        "version": "14.4.0"
      },
      "architecture": "arm",
      "screen": {
        "size": "1440x900",
        "color_depth": 24,
        "pixel_ratio": 2,
        "orientation_type": "landscape-primary"
      },
      "locale": {
        "timezone": "America/Los_Angeles",
        "primary_language": "en-US",
        "languages": ["en-US", "en"]
      },
      "capabilities": {
        "touch": {
          "available": false,
          "max_touch_points": 0
        },
        "storage": {
          "cookies": true,
          "local_storage": true,
          "indexed_db": true,
          "service_worker": true,
          "window_name": true
        },
        "webgpu": {
          "available": false
        },
        "platform_authenticator": {
          "available": true,
          "conditional_mediation": true
        },
        "media_devices": {
          "available": true
        },
        "speech_synthesis": {
          "available": false
        }
      }
    },
    "analysis_coverage": {
      "browser": true,
      "device": true,
      "network": true,
      "runtime": true,
      "behavioral": true,
      "visitor_identity": true
    },
    "signals_fired": [
      {
        "signal": "webdriver_detected",
        "role": "risk",
        "category": "environment",
        "strength": "definitive",
        "signal_score": 100
      },
      {
        "signal": "anti_detect_browser_indicators",
        "role": "risk",
        "category": "environment",
        "strength": "strong",
        "signal_score": 84
      },
      {
        "signal": "software_rendered_graphics_path",
        "role": "risk",
        "category": "fingerprint",
        "strength": "strong",
        "signal_score": 73
      },
      {
        "signal": "virtualization_indicators",
        "role": "risk",
        "category": "environment",
        "strength": "strong",
        "signal_score": 61
      }
    ],
    "client_telemetry": {
      "navigator": {
        "model": null,
        "platform": "macOS",
        "vendor": "Google Inc.",
        "hardware_concurrency": null,
        "device_memory": null,
        "max_touch_points": 0,
        "pdf_viewer_enabled": true,
        "cookie_enabled": true,
        "product_sub": "20030107",
        "primary_language": "en-US",
        "languages": ["en-US", "en"],
        "mime_types_count": 5,
        "plugins": ["PDF Viewer", "Chrome PDF Viewer"]
      },
      "storage": {
        "cookies": true,
        "local_storage": true,
        "session_storage": true,
        "indexed_db": true,
        "service_worker": true,
        "window_name": true
      },
      "canvas": {
        "hash": 123456,
        "geometry_hash": 998877,
        "text_hash": 112233,
        "winding": null,
        "noise_detected": true,
        "offscreen_consistent": true
      },
      "graphics": {
        "webgl": {
          "vendor": "Google Inc.",
          "renderer": "ANGLE (Apple, ANGLE Metal Renderer)",
          "version": "WebGL 1.0",
          "shading_language_version": "WebGL GLSL ES 1.0",
          "parameters_hash": "params_123",
          "extensions_hash": 333444,
          "extension_parameters_hash": "webgl2_456",
          "shader_precision_hash": 777888
        },
        "webgpu": {
          "available": false,
          "adapter_vendor": "Apple",
          "adapter_architecture": "metal",
          "fallback_adapter": false,
          "features_hash": 0,
          "limits_hash": 0
        }
      },
      "audio": {
        "hash": 124.0434,
        "sample_rate": 48000,
        "channel_count": null,
        "voice_count": 3,
        "local_voice_count": 2,
        "default_voice_lang": "en-US",
        "noise_detected": true
      },
      "fonts": {
        "detected_count": 2,
        "tested_count": null,
        "enumeration_hash": 3649417752,
        "metrics_hash": 223344,
        "preferences_hash": null,
        "emoji_hash": 112233
      },
      "media": {
        "device_count": 1,
        "counts_by_kind": {
          "audioinput": 0,
          "audiooutput": 1,
          "videoinput": 0
        },
        "blank_label_count": 1,
        "topology_hash": 123
      }
    },
    "behavior": null
  },
  "meta": {
    "request_id": "req_0123456789abcdef0123456789abcdef"
  }
}

Response fields are grouped by purpose:

decision is the current session outcome in public, action-oriented terms. automation_status maps to automated, human, or uncertain, while decision_status tells you whether the current result is preliminary or final.
highlights is a curated explanation layer capped at five items, including both concerning and reassuring findings.
attribution, web_bot_auth, network, and runtime_integrity summarize the strongest fraud and classification context.
attribution.labels identifies what is behind the session. Each label has a kind (actor, provider, tool, product, organization, purpose, environment, trust, or evasion), a flat string value such as automation, ai-agent, or playwright, a display label, and a confidence from 0 to 100. attribution.behaviors describes how input reached the page, by channel. attribution is null when Foil has nothing to attribute.
Each runtime_integrity field is one of clean, notice, elevated, or high_risk.
visitor_fingerprint and connection_fingerprint provide continuity and transport identity context. visitor_fingerprint.resolution tells you how the session was linked to the visitor ID.
native_runtime_integrity, native_app, native_carrier, native_motion_print, device_identity, and install_id are null for browser sessions. Sessions from the iOS and Android SDKs can populate them, but each field is still null when Foil doesn’t have its data for the session, so check each one before you read it.
behavior is null unless behavior data is enabled for your organization and available for the session.
signals_fired is the structured machine-usable signal summary; highlights is the editorial explanation layer.
client_telemetry is curated lower-level client telemetry for investigations. It is not a verbatim raw probe dump.

signals_fired.signal and highlights.evidence.signal are friendly string slugs. They are response values, not an exhaustive documented enum registry.

`PATCH /v1/sessions/:sessionId`

Sets or clears client_user_id, the ID of the end user in your own database. This is customer-supplied linkage only: it does not affect scoring, visitor fingerprints, sealed tokens, or browser/native SDK behavior. Requires a secret key with the sessions:update scope.

{
  "client_user_id": "user_123"
}

Send null to clear it:

{
  "client_user_id": null
}

The body must include client_user_id. Foil applies these rules to its value:

Value	Result
A string of 1 to 256 characters	Foil trims leading and trailing whitespace and stores the trimmed value. The 256-character limit applies after trimming.
An empty string, or a string that is only whitespace	`422` with the field error `invalid_value`. Send `null` to clear the value instead.
A string longer than 256 characters after trimming	`422` with the field error `too_long`.
Any other type, such as a number	`422` with the field error `invalid_type`.
A body without `client_user_id`	`422` with the field error `required`.

Errors are request.validation_failed responses with details.parameter_set set to session_update. A session that doesn’t exist, or that belongs to the other environment, returns 404. The response is the same session detail resource returned by GET /v1/sessions/:sessionId, with the updated client_user_id. The list endpoint returns client_user_id on each row, and its search parameter matches it.

Get started

Detection

Agents

Webhooks

Management

Sessions API

Endpoint summary

`GET /v1/sessions`

`GET /v1/sessions/:sessionId`

`PATCH /v1/sessions/:sessionId`

​Endpoint summary

​GET /v1/sessions

​GET /v1/sessions/:sessionId

​PATCH /v1/sessions/:sessionId

Endpoint summary

`GET /v1/sessions`

`GET /v1/sessions/:sessionId`

`PATCH /v1/sessions/:sessionId`