Documentation

Getting Started

BotAudit helps you detect bot traffic in your ad campaigns. Set up takes less than a minute:

1. Create a free account
2. Add your site in the dashboard
3. Copy the tracking script to your landing page
4. Start seeing traffic data immediately

Basic Setup

After creating a site in your dashboard, you'll get a tracking script. Add it to your HTML page:

<script src="https://track.botaudit.co/s/YOUR_SITE_KEY.js"></script>

Place this before the closing </body> tag. The script is tiny (<2KB), loads asynchronously, and uses navigator.sendBeacon to avoid blocking page navigation.

Custom Data

You can pass custom key-value data that will be stored with each visit and available for filtering and export:

<script>
  window.botaudit = {
    clientId: 'acme-corp',
    campaignId: 'feb-2026-launch',
    landingPage: 'variant-a'
    // Add any key-value pairs you want
  };
</script>
<script src="https://track.botaudit.co/s/YOUR_SITE_KEY.js"></script>

Important: Set window.botaudit before loading the tracking script. You can then filter by any custom field in the dashboard, and custom data is included in CSV exports.

Classification Logic

Every visit is classified into one of three categories:

Hard Signals (proof of automation on their own)

• navigator.webdriver — Set by automation frameworks
• HeadlessChrome in user agent
• window.__nightmare — NightmareJS
• window.callPhantom / _phantom — PhantomJS
• window.__selenium_unwrapped — Selenium
• navigator.languages empty — Missing browser languages
• Known bot/script user-agent or missing user-agent (checked server-side)
• Zero-size screen — headless environments often report 0×0

Input Physics (catches bots driving real browsers)

Stealth automation drives a real Chrome — the webdriver flag is hidden and the user agent is genuine. What it can't cheaply fake is the input trail a human hand produces. The tracker keeps aggregate counters (mouse-movement, wheel, scroll, touch, and key-press counts plus first-input timing — never keystroke content or cursor paths), and the server derives three anomaly signals:

• Teleport click — a click with zero mouse movement ever observed and no touch input: the cursor teleported to the button
• Instant click — first input is a click landing < 150ms after navigation start, faster than a human can render, read, and react
• Programmatic scroll — the page scrolled with no wheel, touch, key, or mouse movement (scrollTo())

These are treated as probabilistic, not proof: one anomaly alone marks the visit Suspicious; two or more corroborate to Bot. They're derived server-side, so thresholds improve without you redeploying the snippet.

Ad Platform Detection

API Reference

The admin API is available at https://app.botaudit.co/api. Authentication is via httpOnly JWT cookie (set on login).

CSV Export

The CSV export includes all filterable fields. Use it to build evidence for ad platform invalid-traffic disputes.

To export:

1. Go to your site dashboard
2. Apply filters (e.g., Classification = Bot, Platform = Google)
3. Click "Export CSV"
4. Submit the CSV to your ad platform's invalid click form

Exported fields: timestamp, classification, platform, ad_click_id, country, region, city, ISP, hosting provider, device type, interaction, time on page, bot signals, custom data, IP hash.

Google Claim CSV

The "Google Claim CSV" button downloads a ready-to-submit click log for Google's Click Quality Form: paid Google clicks (gclid/gbraid/wbraid) classified bot or suspicious within the last 60 days — Google's dispute lookback window — including the visitor IP address the form asks for, click date/time (UTC), click ID, campaign, and the signals behind each classification.

Visitor IPs are retained only for flagged paid clicks and only for 60 days (see our privacy policy). Visits recorded before this feature launched export with an empty IP column — the click ID still identifies the click to Google.

Tip: set your Google Ads customer ID on the site (Sites → Edit) and it appears in the claim filename and on the printable refund report. Note that Google reviews every claim against its own data and issues ad credits at its discretion — the export documents your claim; it doesn't guarantee a credit.