On this page

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

Missing insert_id or session_id: engineering solution

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 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.

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 after you deploy the insert_id or session_id changes. For deduplication behavior, refer to HTTP V2 event deduplication. For session behavior, refer to Track sessions.

Was this helpful?