This is the only required file. Each row is one event fired by one user.
GEM auto-detects column names — your columns don't need to match exactly.
Column
Required
Example value
Also recognised as
machine_id
Required
machine_0042
user_id, userId, device_id, client_id
event_id
Required
editor.typing:typed
event_name, eventName, event, action
os_name
Optional
macOS
os, platform, operating_system
session_duration
Optional
3600
duration, session_length, duration_seconds
user_session_id
Optional
sess_abc123
session_id, sessionId
Optional. A reference table mapping event IDs to their type.
If omitted, GEM auto-classifies events using keyword matching.
Column
Required
Example value
Also recognised as
event_id
Required
indexing.statistics:started
event_name, event, action
event_type
Optional
tech / user
type, category, event_category
Optional. Used to compute your overall retention rate metric.
One row per user per cohort week.
Column
Required
Example value
Also recognised as
machine_id
Required
machine_0042
user_id, userId, client_id
retained
Required
1 or 0
is_retained, active, returned
cohort_week
Optional
W1
week, cohort, period
Here's how to pull the right data from common tools — no engineering help needed.
📊 Amplitude
Go to Data → Export → select "Raw Events" → filter by date range →
Export as CSV. Rename columns: user_id → machine_id, event_type → event_id.
🔥 Mixpanel
Go to Events → Export → select your date range → choose "CSV" format.
Rename: distinct_id → machine_id, event → event_id.
🗄️ BigQuery / Snowflake
Run: SELECT machine_id, event_id, os_name, session_duration FROM events_table WHERE date >= DATE_SUB(CURRENT_DATE, INTERVAL 30 DAY)
Then export query results as CSV.
💡 Don't have any of these?
Use Load demo data below to explore GEM with realistic synthetic data.
Then forward this schema guide to your data team — the template CSVs above show exactly what's needed.
Upload your sessions.csv (required) to run churn diagnostics, activation funnel analysis, and generate the Strict Report. Use demo data to preview the engine.