Source: https://datafa.st/docs/api/website/bot-traffic/summary
Markdown source: https://datafa.st/docs/api/website/bot-traffic/summary.md
Description: Return accepted Bot traffic totals, companies, exact crawler agents, verification counts, and a timeseries for one website. Use `category=answer_fetch` to answer whether assistants such as ChatGPT fetched pages to answer users.

# Get Bot traffic summary

`GET https://datafa.st/api/v1/analytics/bot-traffic`

Return accepted Bot traffic totals, companies, exact crawler agents, verification counts, and a timeseries for one website. Use `category=answer_fetch` to answer whether assistants such as ChatGPT fetched pages to answer users.

MCP equivalent: `datafast_bot_traffic_summary`. If no dates are supplied, the endpoint returns the last 30 calendar days in the website timezone.

> **Related:** [Bot traffic API](/docs/api/website/bot-traffic) · [MCP tools](/docs/mcp-tools)

## Request

#### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | Required with dft_ | Website ObjectId used by account tokens to choose which website to query or manage. Website ObjectId. Omit with a `df_` website key; required with a `dft_` account token. |
| `startAt` | string | No* | Start of the reporting window. Use it with `endAt` to query a specific date range instead of the endpoint default. Inclusive start as `YYYY-MM-DD` or ISO 8601 with `Z` or a UTC offset. Provide with `endAt`; both default to the last 30 calendar days when omitted. |
| `endAt` | string | No* | End of the reporting window. Must be paired with `startAt` so DataFast can build the date range. Inclusive end as `YYYY-MM-DD` or ISO 8601 with `Z` or a UTC offset. Provide with `startAt`. |
| `timezone` | string | No | Timezone used to interpret dates and group analytics buckets. Defaults to the website timezone. IANA timezone such as `America/New_York`, `Europe/Paris`, or `UTC`. Defaults to the website timezone. |
| `interval` | string | No | Controls how time-series rows are grouped. For example, `day` returns one row per day and `hour` returns one row per hour. `hour`, `day`, `week`, or `month`. Inferred from the requested range when omitted. |
| `category` | string | No | `all`, `answer_fetch`, `search_index`, `training`, or `ai_crawler`. Defaults to `all`. |
| `verification` | string | No | `all`, `ip_verified`, or `user_agent_only`. Defaults to `all` accepted requests. |
| `company` | string | No | Exact company name returned by the API, such as `OpenAI`. Defaults to `all`. |
| `crawlerId` | string | No | Exact ID returned in `crawlers[].id`, such as `OpenAI::ChatGPT-User::answer_fetch`. |

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data` (and `pagination` when the endpoint is paginated).

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[].websiteId` | string | Website ObjectId used by account tokens to choose which website to query or manage. |
| `data[].domain` | string | Tracked domain. |
| `data[].range` | object | Resolved `startAt`, `endAt`, `timezone`, and `interval`. |
| `data[].filters` | object | Resolved category, verification, company, and crawler ID filters. |
| `data[].totalRequests` | number | Accepted requests matching the filters. |
| `data[].aiAnswerRequests` | number | Requests made by an AI assistant to answer a user. |
| `data[].indexingRequests` | number | Search or retrieval indexing requests. |
| `data[].trainingRequests` | number | Model-training crawler requests. |
| `data[].otherCrawlerRequests` | number | Other recognized AI crawler requests. |
| `data[].ipVerifiedRequests` | number | Requests whose crawler IP was verified. |
| `data[].userAgentOnlyRequests` | number | Accepted requests matched only by user agent. |
| `data[].companies[]` | array | Per-company request, category, verification, and percentage totals. |
| `data[].crawlers[]` | array | Exact crawler IDs, companies, user agents, categories, counts, and percentages. |
| `data[].timeseries[]` | array | Time buckets with request, category, and verification totals. |

## Authentication

Use a `df_` website API key for one website, or a `dft_` account token with `analytics:read`.

With `df_`, the website is inferred from the key. With `dft_`, add `websiteId` to the query and make sure the token can access that website.

The account must have active DataFast API access. Read [authentication and scopes](/docs/api/authentication) for token creation and permissions.

### Errors

**400** — Invalid or incomplete date range, timezone, interval, category, verification, company, or crawler ID.

**404** — Website not found or the caller is not its owner.

**500** — Bot traffic analytics could not be queried.

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

```bash
curl -X GET "https://datafa.st/api/v1/analytics/bot-traffic?category=answer_fetch&verification=ip_verified&startAt=2026-08-01&endAt=2026-08-31" \
  -H "Authorization: Bearer df_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": [{
    "websiteId": "665f0b3c4d2e1a0012345678",
    "domain": "example.com",
    "range": {
      "startAt": "2026-08-01T00:00:00.000Z",
      "endAt": "2026-08-31T23:59:59.999Z",
      "timezone": "UTC",
      "interval": "day"
    },
    "filters": {
      "category": "answer_fetch",
      "verification": "ip_verified",
      "company": "all",
      "crawlerId": null
    },
    "totalRequests": 12840,
    "aiAnswerRequests": 12840,
    "indexingRequests": 0,
    "trainingRequests": 0,
    "otherCrawlerRequests": 0,
    "ipVerifiedRequests": 12840,
    "userAgentOnlyRequests": 0,
    "companies": [{
      "company": "OpenAI",
      "requestCount": 8840,
      "aiAnswerRequests": 8840,
      "ipVerifiedRequests": 8840,
      "percentage": 68.85
    }],
    "crawlers": [{
      "id": "OpenAI::ChatGPT-User::answer_fetch",
      "company": "OpenAI",
      "userAgent": "ChatGPT-User",
      "category": "answer_fetch",
      "requestCount": 8840,
      "ipVerifiedRequests": 8840,
      "userAgentOnlyRequests": 0,
      "percentage": 68.85
    }],
    "timeseries": [{
      "date": "2026-08-01",
      "requestCount": 420,
      "aiAnswerRequests": 420,
      "ipVerifiedRequests": 420
    }]
  }]
}
```