---
name: user-cohort-forensics
description: Investigates individual users and user populations in Amplitude — resolve users by email/ID, read profiles, batch-analyze event timelines, spot-check cohort membership. Use for "what did user X do", attribution audits, population sampling, and email-to-user-ID resolution.
---

# User & Cohort Forensics

## The arcs

**Single user deep-dive:** `get_amp_user_data` `include: 'id'` (resolve the
user: email, user ID, device ID, or amplitude ID) → `include: 'profile'`
(lifecycle, acquisition, usage stats) → `include: 'timeline'` (session-aware
event history). `include: 'both'` gets profile + timeline in one call when
you know you'll need both. Summarize journeys; don't dump raw events.

**Population analysis (batched):** build the user set first
(`query_amplitude_data` with a user-ID group_by to rank by volume, or
`use_amplitude_cohorts` `action: 'find'` for a filtered set) →
`get_amp_user_data` `include: 'timeline'` in parallel batches — up to 10
identifiers per call, 10–20 calls in flight is normal for population
analysis; hundreds of calls total is fine. Keep each call narrow (event
types, window) so responses stay small.

**Cohort spot-check:** prefer existing cohorts — `use_amplitude_cohorts`
`action: 'list'` or `action: 'get'` before building ad
hoc definitions. `action: 'membership'` verifies specific users. Check a
member's timeline for the exact markers (purchase, typing, checkout events)
rather than trusting the cohort definition blindly.

**Email → ID resolution:** `get_amp_user_data` `include: 'id'` per email;
uploaded email lists are resolved in batches of ≤10 identifiers per call.
For bulk exports, batch and note the retry pattern on individual failures.

## Parameterization notes

- `include: 'timeline'`: always bound the window (last 30 days by default)
  and pass event-type filters when you know what you're looking for —
  unfiltered timelines are large and slow.
- Rate-limit failures come back flagged `retryable` with `retryAfterMs` —
  back off instead of churning.
- User identity: a user can match multiple IDs (device, user, email). Say
  which identity you resolved and flag ambiguous matches instead of picking
  one silently.