# Import event history

Use explicit backfill mode to import historical server events. Backfill updates history without triggering lifecycle email. This guide covers event history; importing an email design is a separate management action.

## Prerequisites

Read [the event contract](/docs/events.md#emitter-rules). The integration key needs `events:write` and `history:write`. An owner grants the management `history:write` scope before an agent can create a key with that capability.

Use the [installed skill](/docs/guides/quickstart.md)'s `references/emit.ts` as the canonical emitter. Its configuration reads a private integration key from your server environment. Do not expose it in browser code.

## Mark history explicitly

In the server integration that already defines `emit` with `createBaruaEmitter`, send your validated historical records with:

```ts
const result = await emit(historicalEvents, { mode: 'backfill' });
if (!result.ok) {
  throw new Error(`History request failed: HTTP ${result.status}`);
}
const receiptId = (result.body as { receipt_id: string }).receipt_id;
```

The emitter resolves failures as `ok: false`; it does not throw. Check the result and save `receiptId` with your import job before continuing. The default mode is live. Omitting the backfill option changes the meaning of an import. Preserve each event's original `occurred_at` and stable `event_id`; do not generate fresh IDs for retries.

Send `signed_up` first for each person and wait for its receipt to apply before submitting dependent events. The [event schema and limits](/docs/events.md#the-event) define the required identity and properties. Backfill batches accept at most 1,000 events and 2 MiB.

## Wait for application

HTTP 202 means the batch was accepted for processing. Save its `receipt_id`, then read `GET /api/integrations/v1/receipts/{receipt_id}` with the same integration key until the result is settled. Follow [Send events](/docs/events.md#send-events) for the receipt response and error handling.

Report rejected or deferred rows separately. A receipt is stronger evidence than a count of attempted requests, and an accepted receipt is not yet proof that all records were applied.

## Verify safely

Use [people and profiles](/docs/guides/people.md) to inspect the imported data and [workspace diagnostics](/docs/guides/inspect-workspace.md) to examine event outcomes.

Historical events never count as fresh launch proof. Do not replay them in live mode to pass setup checks. A separate authorized fresh event is required for [setup verification](/docs/guides/quickstart.md#verify-the-result).