curl --request GET \
--url https://api.usefoil.com/v1/sessions/breakdownimport requests
url = "https://api.usefoil.com/v1/sessions/breakdown"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.usefoil.com/v1/sessions/breakdown', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.usefoil.com/v1/sessions/breakdown"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://api.usefoil.com/v1/sessions/breakdown")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usefoil.com/v1/sessions/breakdown",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $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
}
],
"other": {
"sessions": 26730,
"bots": 1173,
"humans": 22673,
"inconclusive": 2884
},
"group_count": 7
},
"meta": {
"request_id": "req_cf147349a4134208aebb8c70e25fb7e1"
}
}{
"error": {
"code": "request.validation_failed",
"message": "Observation payload failed validation.",
"status": 1,
"retryable": true,
"request_id": "req_cf147349a4134208aebb8c70e25fb7e1",
"docs_url": "https://app.acme.co/signup",
"details": {
"fields": [
{
"name": "Acme Growth Workspace",
"issue": "required",
"expected": "string",
"received": "any_of"
}
],
"allowed_values": [
"verified"
],
"header_name": "x-forwarded-for",
"parameter_set": "browser_fingerprint",
"next_action": "retry"
}
}
}{
"error": {
"code": "request.validation_failed",
"message": "Observation payload failed validation.",
"status": 1,
"retryable": true,
"request_id": "req_cf147349a4134208aebb8c70e25fb7e1",
"docs_url": "https://app.acme.co/signup",
"details": {
"fields": [
{
"name": "Acme Growth Workspace",
"issue": "required",
"expected": "string",
"received": "any_of"
}
],
"allowed_values": [
"verified"
],
"header_name": "x-forwarded-for",
"parameter_set": "browser_fingerprint",
"next_action": "retry"
}
}
}{
"error": {
"code": "request.validation_failed",
"message": "Observation payload failed validation.",
"status": 1,
"retryable": true,
"request_id": "req_cf147349a4134208aebb8c70e25fb7e1",
"docs_url": "https://app.acme.co/signup",
"details": {
"fields": [
{
"name": "Acme Growth Workspace",
"issue": "required",
"expected": "string",
"received": "any_of"
}
],
"allowed_values": [
"verified"
],
"header_name": "x-forwarded-for",
"parameter_set": "browser_fingerprint",
"next_action": "retry"
}
}
}{
"error": {
"code": "request.validation_failed",
"message": "Observation payload failed validation.",
"status": 1,
"retryable": true,
"request_id": "req_cf147349a4134208aebb8c70e25fb7e1",
"docs_url": "https://app.acme.co/signup",
"details": {
"fields": [
{
"name": "Acme Growth Workspace",
"issue": "required",
"expected": "string",
"received": "any_of"
}
],
"allowed_values": [
"verified"
],
"header_name": "x-forwarded-for",
"parameter_set": "browser_fingerprint",
"next_action": "retry"
}
}
}Break down sessions
Counts the sessions that match the filters, grouped by one dimension, with each group’s bot, human and inconclusive counts. Counts lag new scores by up to five minutes. Requires the sessions:list secret-key scope.
curl --request GET \
--url https://api.usefoil.com/v1/sessions/breakdownimport requests
url = "https://api.usefoil.com/v1/sessions/breakdown"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.usefoil.com/v1/sessions/breakdown', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.usefoil.com/v1/sessions/breakdown"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://api.usefoil.com/v1/sessions/breakdown")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usefoil.com/v1/sessions/breakdown",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $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
}
],
"other": {
"sessions": 26730,
"bots": 1173,
"humans": 22673,
"inconclusive": 2884
},
"group_count": 7
},
"meta": {
"request_id": "req_cf147349a4134208aebb8c70e25fb7e1"
}
}{
"error": {
"code": "request.validation_failed",
"message": "Observation payload failed validation.",
"status": 1,
"retryable": true,
"request_id": "req_cf147349a4134208aebb8c70e25fb7e1",
"docs_url": "https://app.acme.co/signup",
"details": {
"fields": [
{
"name": "Acme Growth Workspace",
"issue": "required",
"expected": "string",
"received": "any_of"
}
],
"allowed_values": [
"verified"
],
"header_name": "x-forwarded-for",
"parameter_set": "browser_fingerprint",
"next_action": "retry"
}
}
}{
"error": {
"code": "request.validation_failed",
"message": "Observation payload failed validation.",
"status": 1,
"retryable": true,
"request_id": "req_cf147349a4134208aebb8c70e25fb7e1",
"docs_url": "https://app.acme.co/signup",
"details": {
"fields": [
{
"name": "Acme Growth Workspace",
"issue": "required",
"expected": "string",
"received": "any_of"
}
],
"allowed_values": [
"verified"
],
"header_name": "x-forwarded-for",
"parameter_set": "browser_fingerprint",
"next_action": "retry"
}
}
}{
"error": {
"code": "request.validation_failed",
"message": "Observation payload failed validation.",
"status": 1,
"retryable": true,
"request_id": "req_cf147349a4134208aebb8c70e25fb7e1",
"docs_url": "https://app.acme.co/signup",
"details": {
"fields": [
{
"name": "Acme Growth Workspace",
"issue": "required",
"expected": "string",
"received": "any_of"
}
],
"allowed_values": [
"verified"
],
"header_name": "x-forwarded-for",
"parameter_set": "browser_fingerprint",
"next_action": "retry"
}
}
}{
"error": {
"code": "request.validation_failed",
"message": "Observation payload failed validation.",
"status": 1,
"retryable": true,
"request_id": "req_cf147349a4134208aebb8c70e25fb7e1",
"docs_url": "https://app.acme.co/signup",
"details": {
"fields": [
{
"name": "Acme Growth Workspace",
"issue": "required",
"expected": "string",
"received": "any_of"
}
],
"allowed_values": [
"verified"
],
"header_name": "x-forwarded-for",
"parameter_set": "browser_fingerprint",
"next_action": "retry"
}
}
}Query Parameters
The dimension to group by. browser_label is the browser and major version (for example Chrome 141); city groups pair each city with its country_code.
browser, browser_label, platform, verdict, country, city, asn "browser"
The number of groups to return, largest first. Sessions in the remaining groups are counted in other.
1 <= x <= 50050
Only sessions whose current verdict is this value.
bot, human, inconclusive "human"
ios, android, macos, windows, linux "ios"
chrome, safari, firefox, edge, webview, arc, helium "chrome"
Exact browser label, as returned in a browser_label breakdown.
200"Chrome 141"
ISO 3166-1 alpha-2 country code of the session's IP address.
^[A-Za-z]{2}$"US"
City of the session's IP address. Combine with country to pick one city of that name.
200"Austin"
Autonomous system number of the session's IP address, with or without the AS prefix.
^(AS|as)?[0-9]{1,10}$"AS7922"
Only sessions whose client_user_id is exactly this value.
1 - 256"user_123"
Only sessions created at or after this time.
"2026-09-01T00:00:00Z"
Only sessions created before this time.
"2026-10-01T00:00:00Z"
Response
Session counts per group.
Show child attributes
Show child attributes
{ "object": "session_breakdown", "group_by": "browser", "total": { "sessions": 48210, "bots": 3105, "humans": 39874, "inconclusive": 5231 }, "groups": [ { "value": "chrome", "label": "chrome", "country_code": "US", "sessions": 21480, "bots": 1932, "humans": 17201, "inconclusive": 2347 } ], "other": { "sessions": 26730, "bots": 1173, "humans": 22673, "inconclusive": 2884 }, "group_count": 7 }
Show child attributes
Show child attributes
{ "request_id": "req_cf147349a4134208aebb8c70e25fb7e1" }