---
title: "Missing insert_id or session_id: engineering solution"
description: Add stable deduplication identifiers to server events and preserve session tracking for client and HTTP API events.
product: data
token_estimate: 640
---
# Missing insert_id or session_id: engineering solution

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

Add a unique `insert_id` to retryable server events and a valid `session_id` to events that should join session analysis. Data Assistant can't populate either field after ingestion, so configure the fields in the SDK, server, or customer data platform mapping. Use the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/event-identifiers-audit) to identify affected sources.

## Add `insert_id` to server events

1. Generate one stable, unique value for each logical event before the first delivery attempt. A UUID works if your system persists the UUID and reuses it for retries.
2. Send the identifier in the top-level `insert_id` field.
3. Reuse the `insert_id` when you retry the same event. Generate a new `insert_id` for a new event.
4. If an event includes `device_id`, use the same `device_id` across retries. Amplitude ignores subsequent events with the same `insert_id` on the same `device_id` within the seven-day deduplication window.
5. Store each `insert_id` long enough to support your retry policy.

## Preserve `session_id` for session analysis

- For Amplitude client SDKs, keep automatic session tracking enabled unless your product uses a custom session policy.
- For HTTP API events that belong to a session, send the session's start time in milliseconds since Unix epoch as the top-level `session_id`.
- Use the same `session_id` for events from the same user in the same session.
- Use `session_id: -1` only for an event that should stay outside session metrics.

> **Note:** A custom session definition is an analysis alternative
>
> An Admin or Manager can define sessions from another property, from starting and ending events, or from a timeout. A custom session definition can support session analysis without changing every payload. The definition doesn't add missing raw `session_id` values and affects session-based charts across the project.

## Validate the fix

Repeat the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/event-identifiers-audit) after you deploy the `insert_id` or `session_id` changes. For deduplication behavior, refer to [HTTP V2 event deduplication](https://amplitude.com/docs/apis/analytics/http-v2#event-deduplication). For session behavior, refer to [Track sessions](https://amplitude.com/docs/data/sources/instrument-track-sessions).