Checkpoints, replay and recovery

A cursor belongs to one Customer/Project and purpose. It cannot authenticate a request or move between activity pagination, refresh pagination, event replay and SSE indiscriminately. Never derive progress from a timestamp, list count or Refresh ID.

Safe current-state handover

1. Authenticate and obtain checkpoint C first using GET /v2/projects/{project_id}/events/checkpoint.
2. Read the bounded current refresh recovery collection with an aware updated_since within seven days. Follow its pages using the same filter, while respecting a local page/time budget.
3. Reconcile those refresh states idempotently. Preserve complete=false and notice=history_unavailable; a budget-limited or incomplete collection is not complete history.
4. Open SSE using Last-Event-ID: C, or read Project events with after=C. Apply returned events and deduplicate overlaps with recovered state.

Taking C after the reads would miss events committed during reconciliation. Advancing to an arbitrary current checkpoint after a gap would hide loss. If C itself is rejected or expires before handover, repeat the recovery procedure within bounded retries and disclose the remaining gap.

A no-cursor stream starts at the current committed position and observes subsequent events. It does not promise historical replay. For an existing valid cursor, replay and live handover use the same durable Project order. The replay HTTP response includes per-item cursors; advance only after application.

Current-state reads

GET /v2/projects/{project_id}/refreshes/{refresh_id} returns safe state/outcome/times and history_available. The collection accepts updated_since, limit and a signed pagination cursor. Its as_of bounds request creation; mutable current state can change between pages. It is not an event commit watermark.

When an owned submission survives but retained Inventory history does not, state/outcome/completion may be null and history_available=false. Treat this as unavailable history, not failure, success or permission to create a new paid refresh. Recovery reads do not materialize new work or settle an existing reservation.

Expired cursor or restored history

HTTP 410 event_recovery_required and the stream recovery control require reconciliation. Reasons include retention, a restore generation change or replay limits. Old keys/generations must not be reused after restore. You may see a duplicate webhook for an event accepted before a restore: keep receiver deduplication across process/database recovery.

Payload history is bounded. Capture gaps and expired-before-projection outcomes are visible as coverage notices, not fabricated events. Do not claim that polling reconstructed every expired event. Display retained-history and coverage limits to users.

Stop on 401/403/404/409 authority errors; authenticate or resolve the Project state before reconnecting. For 429/503, back off with jitter and a bounded Retry-After. See troubleshooting.