# Report views

> The AI Crawl Control reports by view, their filters, and where to read them in the dashboard, the CLI, the API and MCP.

Reports read the classified traffic of the last 30 days. Every role can read them, limited to the token's organization.

## Views

| View | Dashboard | API (`GET …/zones/{zone}/ai-agents/…`) | Shows |
|---|---|---|---|
| `overview` | **Overview** | `report`, `overview`, `summary` | Requests per category and per decision (enforced and "would"), totals, allowed and failed requests, top operators, trap counts. |
| — | **Metrics** | `metrics` | Series by `group_by` (`crawler`, `category`, `operator`, `host`, `content_type`) and `status`; `format=csv`. |
| `crawlers` | **Security** | `crawlers` | Per bot: requests, verified, spoofed, bursts and effective action; `inactive=1` adds catalog bots not seen. |
| `spoofers` | **Security** | `spoofers?bot=<id>` | IPs and ASNs that claimed to be that bot. `bot` is required. |
| `bursts` | **Security** | `bursts` | `agent_burst` clients with the explanation, bots and detections. |
| `optimization` | **Optimization** | `optimization` | Pages AI fetches and demand for pages that fail (including secret probes); `format=csv`. |
| `signals` | **Signals** | `signals` | `robots.txt` per name (fetches, Content-Signal) and violations. |
| `traps` | **Traps** | `traps` | Trap injections over time, who followed them, number of bursts. |
| `endpoints` | **AI endpoints** | `endpoints` | Your AI endpoints: injections, limits, blocks and detections. |
| `events` | Events list on each page | `events` | Notable events, newest first (`kind`, `cursor`, `limit` up to 500). |

The API also has `timeseries` (series per category, `step`), `agents` (bots seen) and `top` (main IPs, TLS fingerprints and ASNs).

## Filters

| Filter | Values |
|---|---|
| `range` | `24h` (default), `7d` or `30d`. Or `since` and `until` (RFC 3339, at most 31 days). The previous period of the same length is always computed for comparison. |
| `host` | One name of the zone. |
| `category` | One [category](https://developers.openwaf.dev/ai-crawl-control/categories/). |
| `bot` | A catalog bot id. |
| `operator` | A bot operator. |

## Event kinds

`spoofed`, `trap_hit`, `injection`, `cost_limit`, `automation`, `wba_invalid`, `tarpit`, `blocked`, `secret_probe`, `robots_violation` and `agent_burst`. A burst event explains itself in `detections`, with labels such as `distinct_endpoints=23/10s`, `burst.id_walk` or `burst.pagination`. Snippets and paths come from requests: they are shown as text, never as HTML.

## Read them

**Dashboard**

Domain → **AI Crawl Control**: **Overview**, **Metrics**, **Security**, **Optimization**, **Signals**, **Traps** and **AI endpoints**. Filters (period, hostname, category, crawler, operator) apply to the whole page; click an event for its details.
**CLI**

```sh
openwaf-cloud ctl ai report example.com --range 7d
openwaf-cloud ctl ai report example.com --view crawlers --host www.example.com
openwaf-cloud ctl ai report example.com --view spoofers --bot googlebot
openwaf-cloud ctl ai report example.com --view events --kind spoofed,trap_hit --limit 100 --json
```
**API**

```sh
curl -sS "https://dash.openwaf.dev/v1/orgs/$ORG/zones/example.com/ai-agents/crawlers?range=7d" \
  -H "Authorization: Bearer $OPENWAF_TOKEN"
```
**MCP**

`ai_agents_report` with `view` (`overview` by default), `range`, `host`, `bot`, `category`, and `kind` and `limit` for events.