Backfill and recomputation

Late events

Kite accepts an event timestamp in the past when it is ISO 8601 and includes a timezone. There is no age cutoff. A late event is inserted as an immutable fact and event windows use its occurrence time. last_event_at remains the latest known timestamp, so an old event does not make an inactive customer look newly active.

Late ingestion recalculates with full event history, but it starts from the customer's current derived state. Terminal lifecycle states and completed journeys can therefore prevent the same result that a clean chronological replay would produce. Use recomputation after authoritative out-of-order corrections.

Backfill procedure

There is no separate import endpoint or kite backfill command. Send historical tracks through the SDK or POST /v1/events/batch in batches of at most 1,000.

1. Deploy the event schema and CS definitions to test.
2. Normalize source timestamps to ISO 8601 with an explicit timezone.
3. Derive a deterministic idempotency key from the source record ID.
4. Preserve chronological order per customer when practical.
5. Start with a small test cohort and inspect timelines and health explanations.
6. Ingest the complete data set, then run a dry-run and persisted recompute.

{
  "type": "track",
  "customerId": "account_42",
  "event": "report.exported",
  "properties": { "format": "csv" },
  "timestamp": "2026-04-02T15:04:05Z",
  "idempotencyKey": "warehouse:exports:98765"
}

Identify operations do not have historical timestamps and are not retained as replayable raw facts. During recomputation, the customer's current traits apply to the entire history. If a rule depends on historical plan or entitlement, encode the relevant value in immutable event properties instead of relying only on current traits.

Recompute

Recompute pins the active config version and evaluation timestamp, then replays each customer's raw events ordered by timestamp and event ID.

kite recompute --customer account_42
kite recompute --all --dry-run
kite recompute --all --yes
kite recompute --all --yes --no-wait

Use --customer while validating one account. A global run requires confirmation. There is no segment-scoped recompute.

A dry-run reports aggregate lifecycle, health, and segment changes without writing state. A persisted run rebuilds lifecycle history, journeys, segments, health history, and rule logs; it does not alter raw events or current traits.

Recompute can append derived timeline emissions without deleting older timeline rows. Receivers must deduplicate webhook event IDs, and operators should not treat the timeline as a unique list of business outcomes across repeated corrective runs.

When to run it

• After a historical backfill or corrected timestamps.
• After changing lifecycle, journey, segment, rule, or health definitions when history should use the new semantics.
• After repairing traits that materially affect current calculations, accepting that current traits apply throughout replay.

Config deployment alone does not recompute existing customers. Schedule large runs outside peak ingestion periods, monitor the returned job until completion, and investigate a dead_letter status rather than immediately starting another global run.