api-integrations
Events API
Pull the audit event stream as paginated JSON with date-range filtering, for full-stream export into your own systems.
Updated Jun 23, 2026
The Events API at /events/v1 exposes the organization’s audit event stream as paginated JSON.
It is the pull side of VaultTerm’s integration surface: where the push
integrations fire a curated set of security-relevant events at your Slack or
SIEM in real time, the Events API lets you walk the full stream on your own schedule and load it
wherever you keep your records.
Authentication
The endpoint accepts either an API token or a user JWT in the Authorization header. For
unattended export, use a scoped API token (see API tokens and SCIM). As
with every API route, the response is row-level-security scoped to the caller’s organization.
curl -H "Authorization: Bearer $API_TOKEN" \
"https://your-host.example.com/api/events/v1?from=2026-06-01&to=2026-06-23"
Filtering and pagination
Results are returned as JSON pages. Narrow the window with a date range and walk the pages until the stream is exhausted:
- Date range — bound the query to a window so you can pull incrementally (for example, fetch the previous hour every hour rather than re-reading everything).
- Pagination — each response returns a page of events; follow the pagination through to the end of the window to capture the complete stream.
Each record is a flat, normalized event (action, title, category, severity, actor, resource, source IP, detail, and timestamp), using the same field names as the push connectors so a record looks the same whether it arrived by push or pull.
Pull versus push
| Events API (pull) | Integrations (push) | |
|---|---|---|
| Direction | You poll /events/v1 | VaultTerm POSTs to your endpoint |
| Coverage | The full audit event stream | A curated catalog of security-relevant events |
| Timing | On your own schedule | Real time, as events occur |
| Best for | Bulk export, archival, full-stream analytics | Alerting and incident response |
Use the Events API to mirror the complete history into a data warehouse or log store; use the push integrations to alert on the events that need a human now. Many teams run both.
The Events API is an Enterprise capability.
Related
- Integrations — real-time push delivery of security events.
- Audit logs — what the audit trail records and how it stays tamper-evident.