Skip to main content
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

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: Rows are ordered by the time of each session’s latest decision, newest first. A limit, verdict, client_user_id, client_application_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, client_application_id, page URL, user agent, and IP address. % and _ match themselves rather than acting as wildcards.
A substring search covers a fixed slice of your sessions per request. Each request picks up where the cursor left off. A page can hold fewer results than limit, or none. An empty page isn’t the end while has_more is true. Keep paging until has_more is false to search all your sessions. The SDK iterators already do this. A search value longer than 256 characters returns 422. A substring search that can’t finish within a second returns 503 with internal.unavailable; retry with a more specific value, or use client_user_id to find a user’s sessions. Example response:
In each row, latest_decision carries these fields:

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:
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.

Look up an application’s sessions

If your product serves other businesses, you can also attach your own ID for the application or organization that a session belongs to, such as a platform customer account, a tenant, or a connected app. Pass the same value as client_application_id to list every session for that application:
The value follows the same rules as client_user_id: the match is exact and case-sensitive, Foil trims surrounding whitespace, and an empty value or one longer than 256 characters returns 422. You can combine client_application_id with client_user_id, verdict, and search, for example to list one user’s sessions within one application. Send the same filters with each cursor.

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: 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, client_user_id, and client_application_id (and search), so it can list the sessions in a verdict group or for one user or application, 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:
Example response:
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:
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 labels lists every value each kind can take. 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. visitor_fingerprint.lifecycle covers the whole organization, including both environments, and resolution_count counts page loads, so one session can count more than once. It is not the same number as seen_count from GET /v1/fingerprints/:visitorId, which counts sessions in your key’s environment.
  • 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.
  • device.capabilities.storage and client_telemetry.storage report whether each storage API is available. A field is true when a probe found the API or Foil read its own identifier back from that store, false only when a probe found the API missing, and null when nothing measured it. indexed_db and window_name have no direct probe, so they are never false.
  • network.ip_address is null when Foil did not capture a client address, and network.location is null when the lookup found no location. network.routing.asn carries an AS prefix, for example AS13335.
  • network.real_location is where the device itself is, as the network edge probe placed it from the device’s own traffic. It differs from network.location when the device connects through a VPN, proxy, or relay that does not hide all of its traffic. city is null when only the device’s DNS server placed it, because a DNS server identifies a country but not a city. network.real_location is null when the probe did not run or placed nothing, and it is always null unless raw signal access is enabled for your organization.
  • network.consistency compares the device’s own location clues with its IP address. Each field is match, mismatch, or unknown, and is unknown when either side of the comparison is missing. timezone compares device.locale.timezone with the IP address’s time zone by area, the part before the first slash, so America/New_York and America/Chicago match while Africa/Lagos and America/New_York do not. language_region compares the country in the device’s locale, such as US in en-US, with network.location.country_code. real_country compares network.real_location.country_code with network.location.country_code.
network.real_location.status is one of the following values: Some fields are deprecated. They stay in the response for compatibility, but they no longer carry information: 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, and client_application_id, the ID of the application or organization on your platform that the session belongs to. Use client_application_id when your product serves other businesses, for example a platform customer account, a tenant, or a connected app. This is customer-supplied linkage only: it does not affect scoring, visitor fingerprints, sealed tokens, or browser/native SDK behavior. Neither value is included in webhook payloads. Requires a secret key with the sessions:update scope. The body accepts client_user_id, client_application_id, or both, and must include at least one. A key you leave out keeps its current value, so you can change one without resending the other. This request sets both:
Send null to clear a key. This request clears the application ID and leaves the user ID as it is:
Foil applies these rules to the value of each key: Errors are request.validation_failed responses with details.parameter_set set to session_update, and each field error names the key it applies to. 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 and client_application_id. The list endpoint returns both on each row, and its client_user_id and client_application_id parameters list every session for one user or one application.