pipeline-history

name	pipeline-history
description	Guides the multi-step workflow of exporting deals and fetching field change history via MCP tools to analyze pipeline progression over time.
when_to_use	Use when analyzing deal pipeline history, stage transitions, funnel conversion, time-in-stage metrics, deal velocity, or stalled deals. Triggers on "pipeline funnel", "how long in stage", "deal progression", "stage duration", "deal history", "conversion rate by stage".

Pipeline History Analysis

When to Use

• Historical pipeline analysis (how deals progressed over time)
• Funnel conversion rates (what % of deals reached each stage)
• Stage duration analysis (how long deals stay in each stage)
• Deal progression timelines (when did a deal move from X to Y)

Workflow

All commands use execute-read-command. Do not pass --json in argv — JSON output is automatic.

Step 1: Identify the Status Field

execute-read-command(command: "field ls", argv: ["--list-id", "YOUR_LIST_NAME"])

Look for a dropdown field tracking deal stages (typically named "Status", "Stage", or "Pipeline Stage"). Note its fieldId (e.g., field-260415).

Step 2: Export Current State

execute-read-command(command: "list export", argv: ["YOUR_LIST_NAME", "--field", "Status", "--max-results", "50"])

JSON output key is data.rows. Each row contains listEntryId, entityId, entityName, and current field values.

Step 3: Estimate API Cost (REQUIRED)

execute-read-command(command: "field history-bulk", argv: ["<field-id>", "--list-id", "YOUR_LIST_NAME", "--dry-run"])

Check estimatedApiCalls before proceeding. Each list entry = 1 API call.

Step 4: Fetch History

execute-read-command(command: "field history-bulk", argv: ["<field-id>", "--list-id", "YOUR_LIST_NAME", "--max-results", "50"])

For all entries (only after confirming cost via dry-run is acceptable):

execute-read-command(command: "field history-bulk", argv: ["<field-id>", "--list-id", "YOUR_LIST_NAME", "--all"])

Step 5: Analyze

Each row has: id, fieldId, entityId, listEntryId, entityName, actionType, value, changedAt, changerName.

Reconstruct transitions: Sort events per entity by changedAt. Each row's value is the value AT that point. Compare consecutive rows to derive old→new transitions.

Common analyses:

• Funnel conversion: Count distinct entities that ever had value = each stage
• Time-in-stage: Duration between consecutive changedAt timestamps for the same entity
• Stage transition matrix: Group by (previous value → current value) pairs
• Stalled deals: Entities with no change event in the last N days

Gotchas

• actionType meanings: create (initial value set), update (value changed), delete (value cleared)
• Each row has a single value, not oldValue/newValue — derive transitions by sorting
• changedAt is UTC
• Some deals may have no history (field set at creation, never changed — only a create event)
• With --list-entry-ids, entityName is null — join with list export data if names needed
• Always --dry-run first to estimate API calls on large lists