Create Amplitude Chart

Create charts from natural language by discovering events, building chart definitions, and verifying results.

Planning First (Critical)

Before any tool calls, decompose the request:

1. Identify chart components:

• •Chart type and metric (what's being measured)
• •Time range (default: Last 30 Days if not specified)
• •Primary event (the action being counted)
• •Segment conditions (user filters/groups)
• •Filters, groupings, breakdowns
• •Funnel steps (if conversion analysis)

2. Plan event searches:

• •ONE search per distinct event concept
• •Never combine multiple concepts in one search
• •Example: "purchase" and "signup" need separate searches

3. Plan parallel tool calls:

• •Get context, search events, find cohorts can run together
• •Wait for results before building definition

Event Discovery (Critical: Discovery First)

IMPORTANT: Cast a wide net before narrowing down

When the user's request is ambiguous or could map to multiple events:

1. •Search BROADLY first to discover relevant options
2. •Review relevant results - look for related events, custom events, meta events
3. •Present options to user OR explain your selection rationale
4. •Try not to assume a single event is the only answer without exploration

Search for events:

Amplitude:search with entity_types=['EVENT', 'CUSTOM_EVENT']

• •Search ONE concept at a time
• •Use broad search terms first (e.g., "AI" not just "AI chat")
• •✓ Good: "user completes purchase"
• •✗ Bad: "signup or purchase events"

Make informed decisions, then explain:

1. •Search broadly to discover all options
2. •Review results and identify the most comprehensive/accurate approach
3. •Make your best judgment call (prefer aggregated custom events over single events)
4. •Always explain: "I found X, Y, Z options. I chose [X] because [reason]. This includes/excludes [scope]."
5. •User can correct if your assumption was wrong

Decision criteria:

• •Prefer custom events that aggregate related activity (e.g., "[2026] Activation Metric [AI events only]")
• •If no aggregated event exists, choose the primary interaction event
• •Consider what "active user" typically means for that product area
• •Default to broader scope unless user specifies narrow focus

Examples:

• •❌ BAD: User asks "weekly AI users" → immediately pick "ai-chat: send message" without exploring, no explanation
• •✅ GOOD: User asks "weekly AI users" → search "AI", find Ask AI, Agents, Visibility, custom aggregated event. Respond: "I found AI activity across Ask AI, Agents, and Visibility. I'm using the '[2026] Activation Metric [AI events only]' custom event which includes all AI product interactions. This gives you total AI users across all features. Let me know if you want to focus on a specific AI product instead."

Verify before use:

• •Get existing charts using the event via search
• •Check event has actual volume (not zero/stale)
• •Look for custom events that aggregate related activity
• •If zero results, search for alternatives

Get properties:

Amplitude:get_event_properties for exact property names/values

Find cohorts:

Amplitude:search with entity_types=['COHORT']
Amplitude:get_cohorts to get full definitions

Chart Type Selection

Quick Reference

eventsSegmentation - Most versatile. Use for:

• •User counts (DAU, WAU, MAU) with uniques metric
• •Event totals, averages, sums of properties
• •Percentiles, distributions, formulas
• •Time series with rolling windows

Aggregation Scope (eventsSegmentation):

• •PROPSUM(A) / metric: "sums" = Global sum across ALL events
• •metric: "frequency" = Distribution of per-user event counts (how many users did it 1x, 2x, 3x)
• •For "distribution of property sum per user": Amplitude does not support this directly. Use metric: "frequency" for event count distributions, or use dataTableV2 grouped by user_id with PROPSUM, then export for external analysis.

funnels - Conversion analysis with predefined steps. Use for:

• •Step-by-step conversion rates when you know the expected sequence
• •Ordered or unordered sequences
• •Time-to-convert (median time between events)
• •Exclusion events, conversion windows
• •Overlapping events: To find users who performed multiple events (in any order), use a funnel with "any order" and set the conversion window to match the chart date range
• •Note: If you want to discover what paths users take, use customerJourney instead

retention - Return behavior. Use for:

• •N-day or rolling retention curves
• •Cohort analysis (new vs returning users)
• •Start event → Return event patterns

dataTableV2 - Tabular data. Use for:

• •Breakdowns by dimensions (country, platform, etc.)
• •Multi-metric comparisons in table format

customerJourney - Path exploration and discovery. Use for:

• •Understanding the actual paths users take (vs. expected paths in funnels)
• •Analyzing paths starting with, ending with, or between two specific events
• •Comparing converted vs dropped-off user paths side by side
• •Discovering unexpected navigation patterns or friction points
• •Exploring path frequency, similarity, or average time to complete
• •Bridging the gap between ideal customer journeys and actual user behavior

sessions - Session-based engagement metrics. Use for:

• •Session duration analysis (average length, time spent, distributions)
• •Session frequency (average sessions per user, total sessions)
• •Time spent per user over time
• •Events performed within sessions (average events per session)
• •Comparing session behavior across user segments

Special metrics:

• •User counts: metric: "uniques"
• •Event counts: metric: "totals"
• •Property sums: metric: "sums" with property in group_by
• •Rates/percentages: Use when comparing groups of different sizes

Meta events:

• •_active: Any active event (DAU, MAU)
• •_new: New users (first-time event)
• •_any_revenue_event: Revenue events

Chart Definition Structure

Core parameters (all chart types):

{
  "name": "Descriptive Chart Title",
  "projectId": "12345",
  "definition": {
    "app": "12345",
    "type": "eventsSegmentation",
    "params": {
      "range": "Last 30 Days",
      "events": [{
        "event_type": "Purchase Completed",
        "filters": [],
        "group_by": []
      }],
      "metric": "uniques",
      "countGroup": "User",
      "interval": 1,
      "segments": [{"conditions": []}]
    }
  }
}

Key parameters:

• •countGroup: "User" (unique users) or "Event" (event occurrences)
• •interval: 1 (daily), 7 (weekly), 30 (monthly)
• •segments: User filters/groups (empty array = all users)

Event filters (inline OR logic):

"filters": [{
  "group_type": "User",
  "subprop_key": "country",
  "subprop_op": "is",
  "subprop_type": "event",
  "subprop_value": ["United States", "Canada"]
}]

User segments (conditions AND logic):

"segments": [{
  "name": "Active Users",
  "conditions": [{
    "type": "property",
    "group_type": "User",
    "prop_type": "user",
    "prop": "plan",
    "op": "is",
    "values": ["Pro", "Enterprise"]
  }]
}]

Cohort segments: Search for cohort, get ID, then:

"segments": [{
  "name": "My Cohort",
  "conditions": [{
    "type": "cohort",
    "group_type": "User",
    "cohort_id": "abc123",
    "op": "is_in"
  }]
}]

Workflow: Create Chart

1. •Get context:

Amplitude:get_context (for projectId)

1. •Discover events (BROAD search first):

Amplitude:search for each distinct concept
- Use broad search terms initially
- Look for all related events, custom events, cohorts
- Review ALL results before selecting

1. •Evaluate and decide:

• •Review all discovered events and custom events
• •Make informed decision (prefer aggregated events)
• •Prepare clear explanation of what you found and your choice

1. •Find similar charts (see examples):

Amplitude:search entity_types=['CHART'] query="similar concept"
Amplitude:get_charts to see definition structure

1. •Get properties if needed:

Amplitude:get_event_properties

1. •Build definition using discovered names

• •Explain event selection rationale in response

1. •Create chart:

Amplitude:query_dataset with full definition

1. •

   Verify results - check data makes sense

2. •

   Save chart:

Amplitude:save_chart_edits with editId from query_dataset

Error Handling

If query_dataset fails:

• •Read error message carefully
• •Common issues: incorrect event names, invalid filters, wrong parameter types
• •Fix definition and retry
• •Verify events exist via search first

If zero results:

• •Check filters aren't too restrictive
• •Verify event has data (search for charts using it)
• •Try broader time range
• •Check segment conditions

Best Practices

Naming:

• •Include metric + time context: "Weekly Active Users Last 90 Days"
• •Not: "WAU" or "Users"

Time ranges:

• •Default to "Last 30 Days"
• •Use inclusive ranges for specific periods
• •State interpreted range explicitly

Verification:

• •Always verify event exists before using
• •Check similar charts to understand event usage
• •Confirm properties with get_event_properties

Comparisons:

• •Use segments for comparing user groups on same chart
• •Use rates/percentages for different-sized groups

Always include:

• •Chart URL in response
• •What the chart shows
• •Key insights from initial data
• •Methodology used