Poll and reconcile events

Before you start

Use an authorised Live API key with events:read at api.kuahr.com. Test keys have no isolated event timeline and receive 409 TEST_MODE_UNSUPPORTED; a missing read grant fails with 403 first. The SDKs and plain HTTP use https://api.kuahr.com.

Fetch and process a page

curl --fail-with-body "https://api.kuahr.com/v1/events?limit=100" \
  -H "X-Api-Key: $KUA_API_KEY"

The result is an array ordered by (occurredAt, id). Process each verified API event idempotently. After the entire page is successfully processed, persist the last event’s exact timestamp string and ID together. A partially processed page can be read again, so deduplicate event IDs with your side effects.

Continue from a durable checkpoint

Send the stored timestamp as since and ID as afterId, preserving fractional precision and offset. Keep the same eventType filter for the traversal. afterId without since is invalid; since alone can skip tied timestamps at a page boundary.

curl --get --fail-with-body "https://api.kuahr.com/v1/events" \
  --data-urlencode 'limit=100' \
  --data-urlencode 'since=2026-11-01T12:00:00.123456+00:00' \
  --data-urlencode 'afterId=80000000-0000-0000-0000-000000000000' \
  -H "X-Api-Key: $KUA_API_KEY"

The sample cursor is illustrative: use the actual last processed event, not that hard-coded value. On restart, load your durable pair. Empty results leave the pair unchanged; wait using bounded polling/backoff instead of looping tightly. Pagination includes Node and Python traversal examples and the 1–500 page limit.

Reconcile late events

A paired cursor handles timestamp ties among persisted rows. It is not a transaction commit sequence or a consistent snapshot across requests. A later commit or backdated event can fall at or before the saved pair and be missed by forward-only polling.

Periodically rescan an earlier timestamp or the complete retained timeline and deduplicate by event ID. A bounded overlap only mitigates late arrival within its window; it cannot promise lossless recovery of older records. Match business outcomes and missing aggregates separately. Polling does not replay webhook deliveries.

Failure and completion states

A failed page must not advance the durable checkpoint. Retry transient reads with backoff; fix permission or validation errors before retrying. A changed filter needs a deliberate checkpoint strategy rather than reusing a cursor from a different traversal.

Done when: your checkpoint advances only after durable processing, restart resumes safely, duplicates do not repeat effects, empty pages back off, and periodic reconciliation has an operational owner. For push delivery and incident recovery, use webhooks.