AI Agent Detection

AI agents and autonomous browsers make up a growing share of web traffic. OpenAI Operator, Claude for Chrome, Perplexity Comet, Browserbase, and other agent frameworks drive real sessions through real browsers, so User-Agent checks alone miss them. cside Device Intelligence surfaces these visitors through the bot object returned by /token/v2/verify in the Events API.

What cside detects

The bot verdict combines two models plus deterministic checks:

• Model 1 scores the device fingerprint and network signals: headless and automation markers (navigator.webdriver, CDP usage, injected automation globals), rendering and font anomalies, TCP and TLS characteristics, and datacenter or hosting IPs
• Model 2 scores in-page behavior: cursor movement, event timing, untrusted (script-dispatched) events, and JavaScript API hooks
• Known agents are matched to a bot_agent_id, such as google-googleother, when the traffic fits a known crawler or agent signature

Together these identify autonomous browser agents, headless browsers (Puppeteer, Playwright, Selenium), instrumented runtimes driven over WebDriver or CDP, and classic crawlers and scrapers. Detection runs server-side after the browser submits telemetry, so changing headers alone does not bypass it.

Reading the bot verdict

Exchange the session token on /token/v2/verify with your backend API key. The response contains a bot object:

{
  "status": "completed",
  "bot": {
    "is_bot": true,
    "bot_probability": 0.94,
    "bot_confidence": 0.88,
    "bot_agent_id": "",
    "reasons": [
      "navigator.webdriver is set",
      "cursor movement scored as automated"
    ],
    "model_1_score": 0.91,
    "model_1_threshold": 0.7,
    "model_2_score": 0.86,
    "model_2_threshold": 0.6,
    "session_event_count": 42
  }
}

Field	Type	Meaning
is_bot	boolean	The verdict. true when the probability crosses the decision threshold or a deterministic check fires.
bot_probability	number	Likelihood the visitor is a bot, from 0 to 1.
bot_confidence	number	How certain the model is in that probability, from 0 to 1. Low confidence usually means little behavioral data was available.
bot_agent_id	string	Identified bot or agent when the traffic matches a known signature. Empty when there is no match.
reasons	string[]	Human-readable explanations behind the verdict.
model_1_score, model_1_threshold	number	Fingerprint and network model score and the threshold applied to it.
model_2_score, model_2_threshold	number	Behavioral model score and its threshold. Absent when no behavioral data was collected.
session_event_count	number	Number of behavioral events the session produced.

Branch on is_bot. Use bot_probability and bot_confidence when you want graded responses, for example a challenge between 0.5 and the threshold and a block above it.

const { status, bot } = data;

if (status !== "completed" || !bot) {
  // Evaluation is pending or failed: fail open
  return allow();
}

if (bot.is_bot) {
  return respondWithChallenge(bot.reasons);
}

Combine the verdict with other signals from the same response for higher confidence:

• Automation fields in fingerprint (web_driver, cdp, tamper_injected_global_ids, tamper_probe_blocked) show the automation evidence directly
• fingerprint.developer_tools_detected is common in locally run agents
• fingerprint.virtual_machine_detected flags sessions running inside a VM or sandbox
• ip_enrichment.hosting and ip_enrichment.is_datacenter_ip flag traffic from cloud providers

Integration example

In your client-side JavaScript, request the fingerprint session token:

const result = await sendClientTelemetry({
  userId: "1234567890",
});

if (result.errors) {
  console.error(result.errors);
  throw new Error("Telemetry request failed.");
}

const { token: sessionToken } = result;

In your backend, exchange the session token with https://api.cside.com/token/v2/verify, then branch on bot.is_bot:

const response = await fetch("https://api.cside.com/token/v2/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ token: sessionToken }),
});

const data = await response.json();

if (!response.ok) {
  throw new Error(data.error || "Fingerprint exchange failed.");
}

if (data.status !== "completed") {
  // 202 pending or a failed evaluation: retry later or fail open
  return allow();
}

if (data.bot?.is_bot) {
  // Block, challenge, or log the request
  return respondWithChallenge();
}

/token/v2/verify returns 202 Accepted with { "status": "pending" } while the evaluation is still processing. Poll again after a short delay or fail open.

In the dashboard

The Bot / Agents row on a session’s Overview tab shows the same verdict with the model scores behind it. The Captured metadata tab lists the bot model features when a feature vector was captured.

Common use cases

• Protect forms and checkout flows - drop agent traffic before it reaches payment or account creation
• Gate AI scraping of priced content - apply different rate limits or access tiers when AI agents are detected
• Measure agent share of traffic - log bot.is_bot, bot_probability, bot_agent_id, and the user_agent string to report on how much of your traffic is automated
• Chargeback and fraud evidence - pair the bot object with fingerprint.device_id to build an audit trail of automated sessions

Next steps

• Read the full Events API reference for the complete response shape
• Review the S3 export bot_evaluation object for the same fields in batch exports
• Contact sales to enable Device Intelligence for your account