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

# Bots

> Returns bot traffic totals, a time series, top bots, and top crawled pages. Prefer a session Bearer token — API keys may receive empty traffic because the underlying action is session-only.

**domain** `string` *required*

Your project's domain, e.g. `example.com`.

**period** `string`

Page period: today, 7d, 30d, 6m, or 12m. Defaults to 7d.

**filter** `string`

Bot category filter: all (default), ai\_answer, indexing, training, or other.

## Response

**period** `string`

Resolved reporting period.

**filter** `string`

Applied bot category filter.

**data.totals** `object`

Counts by category plus all and verified.

**data.series** `array`

Time buckets with per-bot breakdowns.

**data.topBots** `array`

Top bots by crawl count.

**data.topPages** `array`

Most crawled paths.

## Errors

| Status | Error | Description |
| - | - | - |
| `401` | `Invalid or missing API key` | The Authorization header is missing or the Bearer token is invalid. |
| `404` | `Project not found` | No project with that domain exists for the authenticated user. |

```javascript JavaScript theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/bots?period=7d&filter=all", {
  headers: { Authorization: `Bearer ${SESSION_TOKEN}` },
})

const bots = await res.json()
```

```bash cURL theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
curl "https://api.openrevenue.com/api/v1/projects/example.com/bots?period=7d&filter=all" \
  -H "Authorization: Bearer session_token"
```

```json 200 theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
{
  "period": "7d",
  "filter": "all",
  "data": {
    "totals": { "all": 120, "verified": 95, "ai_answer": 40, "indexing": 50, "training": 20, "other": 10 },
    "series": [
      { "date": 1716163200000, "count": 18, "byBot": [{ "name": "Googlebot", "count": 12 }] }
    ],
    "topBots": [
      { "slug": "googlebot", "name": "Googlebot", "category": "indexing", "count": 50, "verified": 48 }
    ],
    "topPages": [
      { "path": "/", "count": 40 }
    ]
  }
}
```


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