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_, orvid_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.
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:
latest_decision carries these fields:
Look up a user’s sessions
After you attach your own user ID to sessions withPATCH /v1/sessions/:sessionId, pass the same value as client_user_id to list every session for that user:
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 asclient_application_id to list every session for that application:
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:
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:
decisionis the current session outcome in public, action-oriented terms.automation_statusmaps toautomated,human, oruncertain, whiledecision_statustells you whether the current result ispreliminaryorfinal.highlightsis a curated explanation layer capped at five items, including both concerning and reassuring findings.attribution,web_bot_auth,network, andruntime_integritysummarize the strongest fraud and classification context.attribution.labelsidentifies what is behind the session. Each label has akind(actor,provider,tool,product,organization,purpose,environment,trust, orevasion), a flat stringvaluesuch asautomation,ai-agent, orplaywright, a displaylabel, and aconfidencefrom0to100. Attribution labels lists every value each kind can take.attribution.behaviorsdescribes how input reached the page, by channel.attributionisnullwhen Foil has nothing to attribute.- Each
runtime_integrityfield is one ofclean,notice,elevated, orhigh_risk. visitor_fingerprintandconnection_fingerprintprovide continuity and transport identity context.visitor_fingerprint.resolutiontells you how the session was linked to the visitor ID.visitor_fingerprint.lifecyclecovers the whole organization, including both environments, andresolution_countcounts page loads, so one session can count more than once. It is not the same number asseen_countfromGET /v1/fingerprints/:visitorId, which counts sessions in your key’s environment.native_runtime_integrity,native_app,native_carrier,native_motion_print,device_identity, andinstall_idarenullfor browser sessions. Sessions from the iOS and Android SDKs can populate them, but each field is stillnullwhen Foil doesn’t have its data for the session, so check each one before you read it.behaviorisnullunless behavior data is enabled for your organization and available for the session.signals_firedis the structured machine-usable signal summary;highlightsis the editorial explanation layer.client_telemetryis curated lower-level client telemetry for investigations. It is not a verbatim raw probe dump.device.capabilities.storageandclient_telemetry.storagereport whether each storage API is available. A field istruewhen a probe found the API or Foil read its own identifier back from that store,falseonly when a probe found the API missing, andnullwhen nothing measured it.indexed_dbandwindow_namehave no direct probe, so they are neverfalse.network.ip_addressisnullwhen Foil did not capture a client address, andnetwork.locationisnullwhen the lookup found no location.network.routing.asncarries anASprefix, for exampleAS13335.network.real_locationis where the device itself is, as the network edge probe placed it from the device’s own traffic. It differs fromnetwork.locationwhen the device connects through a VPN, proxy, or relay that does not hide all of its traffic.cityisnullwhen only the device’s DNS server placed it, because a DNS server identifies a country but not a city.network.real_locationisnullwhen the probe did not run or placed nothing, and it is alwaysnullunless raw signal access is enabled for your organization.network.consistencycompares the device’s own location clues with its IP address. Each field ismatch,mismatch, orunknown, and isunknownwhen either side of the comparison is missing.timezonecomparesdevice.locale.timezonewith the IP address’s time zone by area, the part before the first slash, soAmerica/New_YorkandAmerica/Chicagomatch whileAfrica/LagosandAmerica/New_Yorkdo not.language_regioncompares the country in the device’s locale, such asUSinen-US, withnetwork.location.country_code.real_countrycomparesnetwork.real_location.country_codewithnetwork.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:
null to clear a key. This request clears the application ID and leaves the user ID as it is:
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.