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

typequerystring

Exact event type, or a trailing-segment wildcard such as invoice.*.

streamKeyquerystring

Return only events published with this ordering key.

sincequerystring

RFC 3339 timestamp. Events created strictly after this instant.

untilquerystring

RFC 3339 timestamp. Events created at or before this instant.

limitqueryintegerdefault: 25

Between 1 and 100.

cursorquerystring

Opaque 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" }
    }
  ],
  "nextCursor": "ZXZ0XzAxSFpYOUsyUVc",
  "hasMore": true
}

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.