Collect events

Prerequisites and plan required

Use a Professional or Enterprise key with events scope for event rows. Professional includes a minimum 15-minute delay, 30-day event history, 50,000 rows per key per UTC day and stream access. Enterprise includes no minimum event delay, up to 365-day history and 1,000,000 rows per key per day. Public and Researcher access provides aggregates and bounded public samples, not Events API rows. Collection began on 2026-11-01, so accessible history is still filling.

Expected result: a bounded collector that follows opaque cursors, checkpoints progress and respects delay, history and quotas. Decide where proprietary event data may be stored before building the pipeline; access does not grant redistribution or model-training rights.

1. Choose a stable UTC window

Begin with GET /api/v1/events/recent?limit=100, an alias of /api/v1/events. For repeatable batches, send since and until as RFC 3339 UTC timestamps. Fix the same window for every page; it should end before your plan's delay boundary. Oversized windows and too-recent times are constrained by plan access. Avoid repeatedly fetching the entire history on every poll.

The response contains items and next_cursor. Process returned items using the event id as a deduplication key in your own storage. Keep timestamps and category evidence together rather than reducing an observation to an unlabeled IP list.

2. Follow the cursor

If next_cursor is not null, pass it unchanged as the cursor parameter with the same filters and window. URL-encode it using your HTTP client's parameter support. Do not decode, increment or manufacture cursors. Event pages allow up to 200 rows, subject to remaining daily capacity. Stop when next_cursor is null.

Checkpoint the cursor and fixed window only after successfully storing a page. If your process retries a page after failure, deduplicate by id. When a window completes, advance to the next bounded interval with a small reviewed overlap if your ingestion process needs one; do not assume the API provides exactly-once delivery. Plan storage retention and retry budgets explicitly.

3. Consume a stream when appropriate

GET /api/v1/stream returns text/event-stream. Professional and Enterprise keys include stream access for proprietary per-event frames; event delay, history and row limits still apply. Parse SSE frames with an SSE-capable client, handle connection termination and back off before reconnecting. Do not assume that a stream reconnect provides durable replay. Use bounded event-window collection to reconcile gaps.

4. Download from the Console

Open Console → Events, select a window and filters, then choose Download CSV or Download JSON. Professional and Enterprise can download up to 5,000 rows per Console download. The shown delay and accessible window apply to downloads too. A Console download is separate from the Enterprise API export feature; Professional does not include the full export endpoint capability.

Enterprise API exports are capped at 50,000 rows per call and 20 calls per day. They remain watermarked proprietary data. Check the API reference for export formats and request parameters rather than treating Console downloads as unlimited exports.

Troubleshooting

401 means the API key is absent or invalid. 403 on Events means missing events entitlement. 429 means rate or daily capacity: honor Retry-After and read quota headers. Professional allows 300 requests/minute and 20,000/day; Enterprise allows 600/minute and 100,000/day. Empty items can mean restrictive filters or an inaccessible time window, not an absence of hostile activity. Keep UTC windows and returned metadata in logs while excluding secrets and personal data. Continue with SIEM enrichment or FAQ.