> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bot detection overview

> Overview of ShieldLabs bot detection for AI agents, assistants, search crawlers and browser automation. Understand Good bot, Bad bot and Risk Score results.

## What is ShieldLabs Bot Detection?

ShieldLabs Bot Detection identifies automated activity on your website, including AI agents, AI assistants, search crawlers and browser automation. It analyzes device, browser, network and IP signals, then returns bot detections with the identification and Risk Score.

The dashboard groups bot detections as follows:

* **Good bot**: recognized search bots, AI bots and AI browsers. The dashboard groups these detections under Good bot, and their Risk Score is always 0. The provider name appears when available.
* **Bad bot**: Browser Automation, Device spoofing or JavaScript Disabled was detected. The dashboard groups these signals under Bad bot. Each signal has weight 90; their combined contribution is capped at 90. Read the active signals and request context when protecting an action.

Good bot and Bad bot are dashboard groups. A [scored webhook](https://docs.shieldlabs.ai/api/webhook-identification.md) returns their individual detection flags. Other risk signals can increase the overall score of a bad-bot identification.

## View bot traffic in the dashboard

Open [Overview](https://docs.shieldlabs.ai/dashboard/overview.md#unique-visitors) to see **Good bots** and **Bad bots** in the visitor breakdown. Use [Analytics](https://docs.shieldlabs.ai/dashboard/analytics.md) to investigate individual identifications and their risk signals.

Open an [identification card](https://docs.shieldlabs.ai/dashboard/identification-card.md) for the details of a check. Recognized search and AI bot signals display the provider when available. The dashboard's Good bot and Bad bot groups summarize the underlying detections.

## How ShieldLabs detects bots

ShieldLabs analyzes device, browser, network and IP signals to detect automated activity. The result distinguishes automation and spoofing signals from recognized bot traffic.

### Browser automation and spoofing

Browser checks identify signs of automation, altered device characteristics and unavailable browser capabilities:

| Detection | Webhook flag | What it indicates |
| - | - | - |
| Browser Automation | `detection_flags.browser_automation` | The browser reports automation control |
| Device spoofing | `detection_flags.device_spoofing` | Device characteristics show signs of alteration or spoofing |
| JavaScript Disabled | `detection_flags.javascript_disabled` | JavaScript or browser capabilities required by the check are unavailable |

JavaScript Disabled describes the availability of capabilities required by the check. Use these detections with the protected action and account context.

### Recognized search and AI traffic

ShieldLabs recognizes supported clients from their presented identity and available network evidence. Supported browser platforms can also establish their identity through request signatures.

| Detection | Webhook flag | Provider field |
| - | - | - |
| Search bot | `detection_flags.search_bot` | `search_bot_owner` |
| AI Bot | `detection_flags.ai_bot` | `ai_bot_owner` |
| AI Browser | `detection_flags.ai_browser` | `ai_browser_owner` |

The provider name appears when available. Optional `client_identity` distinguishes recognized names from verified attribution. A known name alone does not establish verified identity; verification coverage depends on the client and evidence.

Browse the [bot directory](https://docs.shieldlabs.ai/features/bot-directory.md) for supported clients. Read [AI agent detection](https://docs.shieldlabs.ai/features/ai-agents.md) for browser-platform verification and [AI assistant detection](https://docs.shieldlabs.ai/features/ai-assistants.md) for assistant fetchers and crawlers.

## How to integrate ShieldLabs bot detection

Bot detection uses your ShieldLabs integration and returns results with the identification. Follow these steps to connect the result to your application:

**1. Create an account and get your API key**

Create your [ShieldLabs account](https://app.shieldlabs.ai/), add your domain and copy its public API key. The [quickstart](https://docs.shieldlabs.ai/quickstart.md) walks through account setup and your first identification.

**2. Install the browser integration**

Add the [JavaScript snippet](https://docs.shieldlabs.ai/setup/snippet.md) or a supported [frontend SDK](https://docs.shieldlabs.ai/api/js-agent.md). Use authenticated checks when you have a signed-in user and anonymous checks otherwise.

**3. Receive and use the server result**

Configure a [scored webhook](https://docs.shieldlabs.ai/setup/webhooks.md), verify its signature and read the bot flags in `data.detection_flags`. Match the result to your action using the Identification ID and validate the expected domain and user context on your backend.

ShieldLabs analyzes the activity received through your integration. For assistant fetchers and crawlers, make sure their requests reach that integration so their activity appears in your results.

### Read a webhook result

This shortened example shows Browser Automation in the scored webhook's `data` object:

```json theme={null}
{
  "identification_id": "13f84f05-7c2a-4e9b-9f1d-2a6b8c0e4d11",
  "risk_score": 90,
  "signals": [{ "name": "browser_automation", "weight": 90 }],
  "detection_flags": { "browser_automation": true }
}
```

Read individual flags to understand the detection. Use `signals` for their reported weights and `risk_score` for the overall result. The complete [webhook reference](https://docs.shieldlabs.ai/api/webhook-identification.md) describes the envelope, delivery identifier and other fields.

Recognized good-bot traffic has `search_bot`, `ai_bot` or `ai_browser` set to `true` and a Risk Score of 0. Apply the result to the access policy for the action your application protects.

### Bot results in webhooks and History

Use a scored webhook for the full bot detection result. History provides a stored identification with a smaller set of fields:

| Result | Scored webhook | History row |
| - | - | - |
| Risk Score | `data.risk_score` | `score` |
| Bot detections | `data.detection_flags` | `is_search_bot`, `is_browser_automation`, `is_js_disabled` |
| Bot provider names | `data.search_bot_owner`, `data.ai_bot_owner`, `data.ai_browser_owner` | Not included |
| Client identity metadata | `data.client_identity`, when supplied | `client_identity`, when supplied |

History rows do not include the `ai_bot` and `ai_browser` flags. Read these flags from the scored webhook rather than treating a missing History field as a negative detection. [History API](https://docs.shieldlabs.ai/api/history.md#response) describes the row format.

The table uses webhook JSON field names. With a server SDK, read the preserved raw webhook data for provider names and `client_identity` when using a normalized identification.

## Next steps

> **[Bot directory](https://docs.shieldlabs.ai/features/bot-directory.md)**
>
> Browse supported search crawlers, AI bots and browser platforms.

> **[Risk signals](https://docs.shieldlabs.ai/features/risk-signals.md)**
>
> Read detection keys, weights and dashboard groups.

> **[AI agent detection](https://docs.shieldlabs.ai/features/ai-agents.md)**
>
> Understand browser-platform signatures and verified attribution.

> **[AI assistant detection](https://docs.shieldlabs.ai/features/ai-assistants.md)**
>
> Interpret assistant fetchers, AI crawlers and their identity metadata.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.