API Reference
List events
Page through published events, filtered by type, stream key, or time.
List events
GET /v1/events
Returns events in reverse chronological order, newest first.
Query parameters
typeExact event type, or a trailing-segment wildcard such as invoice.*.
streamKeyReturn only events published with this ordering key.
sinceRFC 3339 timestamp. Events created strictly after this instant.
untilRFC 3339 timestamp. Events created at or before this instant.
limitBetween 1 and 100.
cursorOpaque cursor from a previous response's nextCursor.
Pagination
Kestrel uses cursor pagination. Keep calling until nextCursor is null.
let cursor = undefined;
const all = [];
do {
const page = await kestrel.events.list({ type: 'invoice.*', limit: 100, cursor });
all.push(...page.data);
cursor = page.nextCursor;
} while (cursor);Cursors expire after 1 hour. A stale cursor returns 400 cursor_expired — restart
the walk from the beginning rather than retrying the same cursor.
Response
{
"data": [
{
"id": "evt_01HZX9K2QW",
"type": "invoice.paid",
"streamKey": "customer_9f2a",
"createdAt": "2026-08-24T09:14:22.481Z",
"apiVersion": "2026-06-01",
"payload": { "invoiceId": "in_1024", "amountCents": 4900, "currency": "usd" }
}
],
Events outside your plan's retention window are not returned and are not counted in
hasMore. See Limits and quotas.
Rate limit
Read endpoints share a 600 requests per minute budget, separate from the publish
budget. Exceeding it returns 429 with a Retry-After header in seconds.