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/breakdown`	Count sessions grouped by browser, platform, location, network, or verdict. 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.
`client_user_id`	string	-	Returns only sessions whose `client_user_id` is exactly this value. See Look up a user’s sessions.

Rows are ordered by the time of each session’s latest decision, newest first. A limit, verdict, client_user_id, 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.

Look up a user’s sessions

After you attach your own user ID to sessions with PATCH /v1/sessions/:sessionId, pass the same value as client_user_id to list every session for that user:

curl "https://api.usefoil.com/v1/sessions?client_user_id=user_123" \
  -H "Authorization: Bearer sk_live_..."

The match is exact and case-sensitive. Foil trims surrounding whitespace from the value, as it does when you attach one, and an empty value or one longer than 256 characters returns 422. You can combine client_user_id with verdict and search, and page through the results with cursor as usual; send the same client_user_id with each cursor. To read the signals for a session in the list, retrieve it with GET /v1/sessions/:sessionId. Use client_user_id rather than search to find a user’s sessions. search matches substrings across several fields, so it can also return sessions for other users whose IDs contain the value.

`GET /v1/sessions/breakdown`

Counts the sessions that match a set of filters, grouped by one dimension, with the number of bot, human, and inconclusive verdicts in each group. Use it to answer questions such as which browsers account for the sessions from one city, or which networks the bots on a platform come from. Requires a secret key with the sessions:list scope. Supported query parameters:

Parameter	Type	Default	Notes
`group_by`	`browser`, `browser_label`, `platform`, `verdict`, `country`, `city`, or `asn`	-	Required. The dimension to group by.
`limit`	integer	`50`	The number of groups to return, from `1` to `500`, largest first.
`verdict`	`bot`, `human`, or `inconclusive`	-	Counts only sessions whose latest decision has this verdict.
`platform`	`ios`, `android`, `macos`, `windows`, or `linux`	-	Counts only sessions on this platform.
`browser`	`chrome`, `safari`, `firefox`, `edge`, `webview`, `arc`, or `helium`	-	Counts only sessions from this browser family.
`browser_label`	string	-	Counts only sessions with this exact browser label, such as `Chrome 141`.
`country`	string	-	ISO 3166-1 alpha-2 code of the session’s IP address, such as `US`.
`city`	string	-	City of the session’s IP address. Combine it with `country` to select one city where several share a name.
`asn`	string	-	Autonomous system number of the session’s IP address, such as `AS7922` or `7922`.
`client_user_id`	string	-	Counts only sessions whose `client_user_id` is exactly this value.
`since`	ISO 8601 timestamp	-	Counts only sessions created at or after this time.
`until`	ISO 8601 timestamp	-	Counts only sessions created before this time.

Each group’s value is in the form its filter parameter accepts, so you can pass it back to this endpoint as a filter to narrow further. For city groups, pass the group’s country_code as country along with the city. GET /v1/sessions filters only by verdict and client_user_id (and search), so it can list the sessions in a verdict group or for one user, but not in a browser, platform, location, or network group. A test key counts test sessions and a live key counts live sessions. An unknown parameter, a value that isn’t valid, or a parameter that is empty or given more than once returns 422 with request.validation_failed. Foil rejects these rather than ignoring them so that a misspelled or malformed filter can’t return counts for sessions you didn’t ask about. A breakdown that doesn’t finish within 20 seconds returns 503; narrow since and until or add filters, then retry. Counts include new decisions within about five minutes. For example, to see the top browsers among sessions from Austin in September:

curl "https://api.usefoil.com/v1/sessions/breakdown?group_by=browser&country=US&city=Austin&since=2026-09-01T00:00:00Z&until=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer sk_live_..."

Example response:

{
  "data": {
    "object": "session_breakdown",
    "group_by": "browser",
    "total": { "sessions": 48210, "bots": 3105, "humans": 39874, "inconclusive": 5231 },
    "groups": [
      { "value": "chrome", "label": "chrome", "sessions": 21480, "bots": 1932, "humans": 17201, "inconclusive": 2347 },
      { "value": "safari", "label": "safari", "sessions": 14206, "bots": 288, "humans": 12644, "inconclusive": 1274 },
      { "value": "webview", "label": "webview", "sessions": 9035, "bots": 702, "humans": 7480, "inconclusive": 853 }
    ],
    "other": { "sessions": 3489, "bots": 183, "humans": 2549, "inconclusive": 757 },
    "group_count": 7
  },
  "meta": {
    "request_id": "req_0123456789abcdef0123456789abcdef"
  }
}

Field	Meaning
`total`	Every session the filters match.
`groups`	The largest groups, up to `limit`. `label` is the country name for `country` groups and the network operator for `asn` groups, and otherwise matches `value`.
`other`	Sessions in the groups beyond `limit`. `total` is the sum of `groups` and `other`.
`group_count`	The number of distinct groups before `limit` was applied.

Sessions whose platform or browser Foil doesn’t recognize are grouped under other when you group by platform or browser. An iPad that requests desktop websites is counted as macos.

`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": null,
        "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 client_user_id parameter lists every session for one user.

Get started

Detection

Agents

Webhooks

Management

Sessions API

Endpoint summary

`GET /v1/sessions`

Look up a user’s sessions

`GET /v1/sessions/breakdown`

`GET /v1/sessions/:sessionId`

`PATCH /v1/sessions/:sessionId`

​Endpoint summary

​GET /v1/sessions

​Look up a user’s sessions

​GET /v1/sessions/breakdown

​GET /v1/sessions/:sessionId

​PATCH /v1/sessions/:sessionId

Endpoint summary

`GET /v1/sessions`

Look up a user’s sessions

`GET /v1/sessions/breakdown`

`GET /v1/sessions/:sessionId`

`PATCH /v1/sessions/:sessionId`