---
title: Bot request metrics
summary: Historical Stats API returns a time series response of bot-request metrics broken down by bot-type.
url: https://www.fastly.com/documentation/reference/api/metrics-stats/bots
---

Historical Stats API returns a time series response of bot-request metrics broken down by bot-type.

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `bot` | string | Bot identifier for which data was recorded. Present only when grouped by bot. |
| `bot_edge_requests_allowed_count` | integer | Count of edge requests where a bot was detected and the request was allowed by the configured policy. |
| `bot_edge_requests_blocked_count` | integer | Count of edge requests where a bot was detected and the request was blocked by the configured policy. |
| `bot_edge_requests_challenge_token_valid_count` | integer | Count of edge requests where a bot was detected and the client making the request has already solved a challenge issued by the configured policy. |
| `bot_edge_requests_challenged_count` | integer | Count of edge requests where a bot was detected and a client challenge was issued for the request by the configured policy. |
| `datacenter` | string | Datacenter (POP) for which data was recorded. Present only when grouped by datacenter. |
| `timestamp` | string | Timestamp for the time series being reported. |
| `meta` | object | Meta information about the scope of the current response and optional additional information for subsequent requests. |

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `from` | string | An RFC-8339-formatted date and time string indicating the inclusive start of the query time range. |
| `group_by` | string | List of dimensions (comma-separated) being summed over in the results. |
| `limit` | integer | The maximum number of results to return. Defaults to 1000. |
| `next_cursor` | string | Optional string that can be used to request the next page of results, if any. |
| `to` | string | An RFC-8339-formatted date and time indicating the exclusive end of the query time range. |

## API endpoints

### Get per-service historical time series metrics for bot requests broken down by bot-type

**GET** `/metrics/bots/entities/{service_id}/{granularity}`

Return historical time series metrics for bot requests broken down by bot-type.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `bot` | string | query | No | Filter results based by Bot ID. |
| `cursor` | string | query | No | Cursor value from the <code>next_cursor</code> field of a previous response, used to retrieve the next page. To request the first page, this should be empty. |
| `datacenter` | string | query | No | Limit query to one or more specific POPs. Values should be comma-separated. |
| `from` | string | query | No | A valid RFC-8339-formatted date and time indicating the inclusive start of the query time range. If not provided, a default is chosen based on the provided <code>granularity</code> value. |
| `granularity` | null | path | Yes | Duration of sample windows. |
| `group_by` | null | query | No | Field to group by in the query. For example, <code>group_by=bot_id</code> will return entries grouped by <code>timestamp</code> and <code>bot_id</code>. |
| `limit` | string | query | No | Number of results per page. The maximum is 10000. |
| `metric_set` | null | query | No | The metric set to retrieve. |
| `metric` | string | query | No | One or more metrics to retrieve. Multiple values should be comma-separated. |
| `region` | null | query | No | Limit query to one or more specific geographic regions. Values should be comma-separated. |
| `service_id` | string | path | Yes | Alphanumeric string identifying the service. |
| `to` | string | query | No | A valid RFC-8339-formatted date and time indicating the exclusive end of the query time range. If not provided, a default is chosen based on the provided <code>granularity</code> value. |