Idempotency keys

The create-event endpoint now accepts an optional idempotency_key. When two events arrive with the same key, the second is treated as a duplicate and dropped instead of recorded again. This makes event submission safe to retry after a timeout or network failure without double-counting usage or burning credits twice. The key is optional, so existing integrations keep working unchanged.

Historical event timestamps

Two new optional fields on the track endpoint let you control an event's effective timestamp instead of using server receipt time. Both require a secret API key. trusted_client_clock uses your sent_at value as the event time and still runs all billing: credits are consumed, Stripe meter events report at the logical time, and usage webhooks fire.

Use it to correct recent usage, within 5 minutes ahead and 34 days back. backfill is analytics-only. Events land at their logical time but skip every billing side effect, including credit consumption, Stripe reporting, usage webhooks, auto top-up, and last-seen updates. Use it to import historical usage up to 365 days back. ClickHouse event retention moved from 60 to 365 days to match.