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

# AI crawler report

> POST /v1/reports/bots

AI crawler and search-bot hits from your own server logs, grouped by any of date, hour, bot, provider, bot type, path and page type. Needs an [integration](/agent-analytics/integrations/overview) installed on the site.

Spoofed hits — a request using GPTBot's name from an address OpenAI does not publish — are left out unless your filter mentions `verified`.

## Body

**site\_id** `string` *required*

The site's id, from [List sites](/api-reference/endpoints/list-sites).

**start\_date** `string` *required*

Inclusive day, `YYYY-MM-DD`, in `timezone`.

**end\_date** `string` *required*

Inclusive day, `YYYY-MM-DD`, in `timezone`. At most 400 days after `start_date`.

**timezone** `string` (default: UTC)

IANA zone for `date` and `hour` buckets and for the day boundaries, e.g. `Asia/Karachi`.

**group\_by** `enum\<string\>[]`

Up to 3 of: `date`, `hour`, `bot_name`, `bot_provider`, `bot_type`, `path`, `page_type`.

**metrics** `enum\<string\>[]`

Any of: `hits`, `pages`, `verified_share`, `error_hits`, `last_visit`.

**filter** `object`

Fields `bot_name`, `bot_provider`, `bot_type`, `verified`, `path`, `page_type`. See [Filtering](/api-reference/filtering).

**sort** `object`

**properties**

**field** `string` *required*

One of the requested `group_by` fields or `metrics`.

**dir** `enum\<string\>` (default: desc)

One of: `asc`, `desc`.

**limit** `integer` (default: 100)

Rows per page, 1–500.

**cursor** `string`

Opaque cursor from `info.next_cursor`.

## Response

**info** `object`

**properties**

**count** `integer`

Rows in this page.

**total\_results** `integer`

Rows across all pages.

**next\_cursor** `string`

Pass as `cursor` for the next page; null on the last page.

**site\_id** `string`

**start\_date** `string`

**end\_date** `string`

**timezone** `string`

**data** `object[]`

**properties**

**date** `string`

**hour** `string`

`YYYY-MM-DDTHH:00` in the requested time zone.

**bot\_name** `string`

e.g. `GPTBot`, `ClaudeBot`, `PerplexityBot`.

**bot\_provider** `string`

**bot\_type** `string`

`ai_assistant`, `ai_training`, `index` or `ai_agent`.

**path** `string`

**page\_type** `string`

`blog_editorial`, `product_page`, `docs_support`, `landing_page`, `brand_about`, `pricing`, `ugc_page`, `technical_infra` or `other`.

**hits** `integer`

**pages** `integer`

Distinct paths requested.

**verified\_share** `number`

0–1: share of hits from IP ranges the provider publishes. Providers that publish no ranges read 0.

**error\_hits** `integer`

Hits answered with a 4xx or 5xx.

**last\_visit** `string`

```bash cURL theme={"system"}
curl -X POST https://api.rankraft.ai/v1/reports/bots \
  -H "X-API-Key: $RANKRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "3f2c9a10-7b1e-4c55-9d2a-1a2b3c4d5e6f",
    "start_date": "2026-09-01",
    "end_date": "2026-09-30",
    "timezone": "Asia/Karachi",
    "group_by": ["bot_name"],
    "metrics": ["hits", "pages", "verified_share"]
  }'
```

```javascript JavaScript theme={"system"}
// npm install rankraft-js · https://www.npmjs.com/package/rankraft-js
import { RankRaft } from "rankraft-js";

const rr = new RankRaft(); // reads RANKRAFT_API_KEY

const rows = await rr.reports
  .bots({
    site_id: "3f2c9a10-7b1e-4c55-9d2a-1a2b3c4d5e6f",
    start_date: "2026-09-01",
    end_date: "2026-09-30",
    timezone: "Asia/Karachi",
    group_by: ["bot_name"],
    metrics: ["hits", "pages", "verified_share"],
  })
  .all(); // every page
for (const row of rows) console.log(row.bot_name, row.hits, row.verified_share);
```

```python Python theme={"system"}
# pip install rankraft-py · https://pypi.org/project/rankraft-py/
from rankraft import RankRaft

with RankRaft() as rr:  # reads RANKRAFT_API_KEY
    page = rr.reports.bots(
        site_id="3f2c9a10-7b1e-4c55-9d2a-1a2b3c4d5e6f",
        start_date="2026-09-01",
        end_date="2026-09-30",
        timezone="Asia/Karachi",
        group_by=["bot_name"],
        metrics=["hits", "pages", "verified_share"],
    )
    for row in page.all():  # every page
        print(row["bot_name"], row["hits"], row["verified_share"])
```

```json 200 theme={"system"}
{
  "info": {
    "site_id": "3f2c9a10-7b1e-4c55-9d2a-1a2b3c4d5e6f",
    "start_date": "2026-09-01",
    "end_date": "2026-09-30",
    "timezone": "Asia/Karachi",
    "count": 2,
    "total_results": 2,
    "next_cursor": null
  },
  "data": [
    { "bot_name": "GPTBot", "hits": 1840, "pages": 212, "verified_share": 0.99 },
    { "bot_name": "ClaudeBot", "hits": 960, "pages": 180, "verified_share": 0 }
  ]
}
```


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