# Security events

> Search, filter and stream live every request the edge blocked, challenged or logged, from the dashboard or the API.

A **security event** is recorded when the edge blocks, challenges or logs a request: a WAF rule, a rate limit, an IP or country rule, a shield, or an origin TLS error (`525`/`526`). Events reach the dashboard shortly after they happen and are kept for 30 days.

## Event fields

| Field | Meaning |
|---|---|
| `ts` | Time of the request. |
| `action` | `block`, `challenge`, `log` or `allow`. |
| `host`, `method`, `path`, `status` | The request and the status the edge answered. |
| `ip`, `country_code`, `asn` | The client's address, its country and network. |
| `rule_id`, `rule_name`, `attack_type`, `msg` | The rule that matched and why. Rate limiting rules appear as `rate_rule:<id>`; origin TLS errors as `origin_tls`. |
| `user_agent`, `tls_fingerprint` | The client software. |

## Explore events in the dashboard

Go to **Analytics › Traffic** and scroll to **Security events**.

- **Time range**: last 5 minutes, 15 minutes, hour, 24 hours or 7 days, or a **Custom range**.
- **Filters**: select **Add filter**, or the + / − buttons on any value in the table, to include or exclude a field (*is* / *is not*). Filters show as chips you can toggle or remove.
- **Search**: free text over path, IP, rule, user agent and other fields.
- **Histogram**: events over time by action; select a bar to zoom into its interval.
- **Breakdown**: events by action, top rules, top rate limiting rules and top countries.
- **Rows**: open a row for every field, as a table or JSON; choose visible fields with **Columns**.
- **Live**: streams new events as they arrive. It pauses while the pointer is over the list, while you browse it or scroll, and while the browser tab is hidden.

## Read events with the API

| Route | Answer |
|---|---|
| `GET /v1/orgs/{org}/zones/{zone}/events` | Events, newest first: `items` and `next_cursor` for the next page. |
| `GET /v1/orgs/{org}/zones/{zone}/events/summary` | `total`, `by_action`, `top_rules`, `top_rate_rules`, `top_countries`. |
| `GET /v1/orgs/{org}/zones/{zone}/events/histogram?step=<s>` | Events per interval and action; `step` from 1 to 86400 seconds, at most 1000 intervals (omit for an automatic step of at most 60 intervals). |
| `GET /v1/orgs/{org}/zones/{zone}/events/stream` | Live stream (Server-Sent Events). |

Any role of the organization can read them, including read-only and zone-scoped tokens.

### Parameters

| Parameter | Meaning |
|---|---|
| `since`, `until` | RFC 3339 times. Default: the last 24 hours; at most 31 days. |
| `action`, `rule_id`, `rule_name`, `rate_rule`, `ip`, `country`, `host`, `path`, `status` | Include only events with this value. Repeatable (up to 20 values each). |
| `not_action`, `not_ip`, … | The same fields with `not_`: exclude events with this value. |
| `q` | Free-text search, up to 200 characters. |
| `limit`, `cursor` | Page size (default 100, at most 1000) and the `next_cursor` of the previous page (`/events` only). |

```sh
curl -s "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/events?action=block&country=CN&not_path=/health&limit=50" \
  -H "Authorization: Bearer $OPENWAF_TOKEN"
```

### Live stream

`/events/stream` accepts the same filters and sends Server-Sent Events:

| Event | Data |
|---|---|
| `ready` | Stream parameters (`poll_ms`, `heartbeat_ms`, `max_age_s`). |
| `event` | One security event, with an `id`. |
| `ping` | Keep-alive when nothing happened for a while. |
| `bye` | The stream ends after 10 minutes; reconnect with `Last-Event-ID` to resume where you left off. |

```sh
curl -sN "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/events/stream?action=block" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" -H "Accept: text/event-stream"
```

An organization can hold up to 10 streams at once; more answer `429` (`too_many_streams`).

## Related

- [WAF](https://developers.openwaf.dev/waf/): the rules behind the events.
- [Troubleshooting 525 and 526](https://developers.openwaf.dev/ssl/troubleshooting/): origin TLS events.