---
title: "getBotDetection() · Nuxt Robots · Nuxt SEO"
canonical_url: "https://nuxtseo.com/docs/robots/nitro-api/get-bot-detection"
last_updated: "2026-08-15T11:00:30.655Z"
meta:
  description: "Server-side composable to access bot detection state in Nitro routes and middleware."
  "og:description": "Server-side composable to access bot detection state in Nitro routes and middleware."
  "og:title": "getBotDetection() · Nuxt Robots · Nuxt SEO"
---

Nuxt SEO on GitHub

Switch to RobotsSwitch to Nuxt SEOSwitch to SitemapSwitch to OG ImageSwitch to Schema.orgSwitch to Link CheckerSwitch to SEO UtilsSwitch to Site ConfigSwitch to Skew ProtectionSwitch to AI Ready

**Nitro API**

# **getBotDetection()**

## Introduction

**Type:** `**function getBotDetection(event: H3Event): BotDetectionContext**`

Perform bot detection using request headers in server-side Nitro routes, middleware, and API handlers.

This function analyzes HTTP headers to detect known bots and returns detailed classification information.

**🔔 Important:** Bot detection only runs when you explicitly call these utility functions. No automatic bot detection occurs - it's entirely opt-in based on your usage of these functions.

## Usage

### Basic Detection

```ts
// server/api/example.ts
import { getBotDetection } from '#robots/server/composables/getBotDetection'
import { defineEventHandler } from 'h3'

export default defineEventHandler(async (event) => {
  const detection = getBotDetection(event)

  if (detection.isBot) {
    return { message: 'Bot detected', bot: detection.botName }
  }

  return { message: 'Human user' }
})
```

### Helper Functions

```ts
// server/api/bot-check.ts
import { getBotInfo, isBot } from '#robots/server/composables/getBotDetection'
import { defineEventHandler } from 'h3'

export default defineEventHandler(async (event) => {
  // Simple boolean check
  if (isBot(event)) {
    return { isBot: true }
  }

  // Get detailed bot info
  const botInfo = getBotInfo(event)
  return { isBot: false, info: botInfo }
})
```

### Middleware Usage

```ts
// middleware/bot-filter.ts
import { getBotDetection } from '#robots/server/composables/getBotDetection'
import { createError, defineEventHandler } from 'h3'

export default defineEventHandler(async (event) => {
  const detection = getBotDetection(event)

  // Block untrusted bots from API routes
  if (event.node.req.url?.startsWith('/api/') && detection.isBot && !detection.trusted) {
    throw createError({
      statusCode: 403,
      statusMessage: 'Bot access denied'
    })
  }
})
```

## Return Type

### `**getBotDetection()**`

Returns the complete bot detection context:

```ts
interface BotDetectionContext {
  isBot: boolean
  userAgent?: string
  detectionMethod?: 'headers' | 'fingerprint'
  botName?: BotName // 'googlebot', 'twitterbot', 'claude', etc.
  botCategory?: BotCategory // 'search-engine', 'social', 'ai', etc.
  trusted?: boolean // Whether this is a legitimate bot
}
```

**`**isBot()**`**: **Type:** `**function isBot(event: H3Event): boolean**`. Simple boolean check for bot detection.

### `**getBotInfo()**`

**Type:** `**function getBotInfo(event: H3Event): BotInfo | null**`

Returns bot details if detected:

```ts
interface BotInfo {
  name?: BotName // Specific bot name ('googlebot', 'facebook', etc.)
  category?: BotCategory // Bot category ('search-engine', 'social', etc.)
  trusted?: boolean // Legitimacy flag
  method?: 'headers' | 'fingerprint' // Detection method
}
```

## Detection Methods

- **headers**: Detected via HTTP headers and user agent analysis
- **fingerprint**: Detected via client-side browser fingerprinting (only available after client hydration)

## Availability

The bot detection state is available:

- ✅ **Server routes**: Immediately available
- ✅ **API handlers**: Immediately available
- ✅ **Middleware**: Immediately available
- ✅ **Server plugins**: Immediately available

Note that client-side fingerprint detection results are only available after the client has loaded and run the detection.

## Pure Utility Functions

For use outside of Nuxt/Nitro contexts, import from `**/util**`:

```ts
import { getBotDetection, getBotInfo, isBot } from '@nuxtjs/robots/util'

// Works with any headers object
const headers = { 'user-agent': 'Mozilla/5.0 (compatible; Googlebot/2.1)' }

const detection = getBotDetection(headers)
// { isBot: true, botName: 'googlebot', botCategory: 'search-engine', ... }

const isBotDetected = isBot(headers)
// true

const botInfo = getBotInfo(headers)
// { name: 'googlebot', category: 'search-engine', trusted: true, method: 'headers' }
```

These pure functions work in any JavaScript environment and don't require H3 events or Nuxt context.

**Was this page helpful?**

### **Related **

[**useBotDetection()**](https://nuxtseo.com/docs/robots/api/use-bot-detection)

[**Bot Detection**](https://nuxtseo.com/docs/robots/guides/bot-detection)

[**getPathRobotConfig()**](https://nuxtseo.com/docs/robots/nitro-api/get-path-robot-config)

[**getPathRobotConfig()** See if a path is indexable within Nitro.](https://nuxtseo.com/docs/robots/nitro-api/get-path-robot-config) [**Nitro Hooks** Learn how to use Nitro hooks to modify the robots final output.](https://nuxtseo.com/docs/robots/nitro-api/nitro-hooks)