diff --git a/docs/vantage/audit-log.md b/docs/vantage/audit-log.md
index e4e753f..46d9a74 100644
--- a/docs/vantage/audit-log.md
+++ b/docs/vantage/audit-log.md
@@ -47,5 +47,16 @@ for accountability.
 
 ## Getting events out
 
-`GET /api/audit` returns recent events as JSON and accepts a `limit`. There is
-no streaming or push export; if you need events in a SIEM, poll that endpoint.
+`GET /api/audit` returns one page of events as JSON:
+
+```json
+{ "events": [ ... ], "total": 3214 }
+```
+
+It accepts `limit` (default 50, maximum 200), `skip`, `q` to search actor,
+details and event type, and `category` to match the part of an event type
+before the dot — `workflow`, `key`, `server`. `total` counts everything
+matching the filter, not the page, so a short page is not the end of the log.
+
+There is no streaming or push export; if you need events in a SIEM, poll that
+endpoint, walking `skip` until you have `total`.