Skip to main content

Aggregate Deal Stage History

POST 

/v1/deals/stage-history/aggregate

Groups recorded stage transitions across every deal in the organization and returns counts per group — the funnel and pipeline-velocity counterpart to the per-deal Get Deal Stage History endpoint.

Group by one of to_stage, from_stage, changed_at, changed_by, deal_id, company_name — or any deal field id (standard or tenant custom, the same ids Aggregate Deals takes). A deal field reflects the deal's CURRENT value, not its value at the time of the transition, and group_by_granularity still requires changed_at. Stage and user groups are returned with their display name as the group key and the raw id alongside (stageId / userId); a deal's creation row has no previous stage and groups under Deal created.

To cross 2 to 3 distinct history fields other than the [<field>, "changed_at"] pair (not deal fields), pass them as group_by entries, e.g. ["to_stage", "deal_id"]; each group then carries _id (the raw value per key, to filter on) and labels (the display text per key), and a changed_at key needs group_by_granularity.

Set count_by to deals to count distinct deals instead of transitions — required for a funnel or a conversion rate, so a deal that re-entered a stage is not counted twice. totalCount is the sum of the group counts, so under count_by: deals a deal is counted once per group it appears in.

Only transitions the platform recorded are visible. A deal that predates this history, or whose stage arrived through an import, contributes no row; use Aggregate Deals with a stage or stages_visited filter when the question is about a deal's present stage. A history row whose deal has since been deleted is excluded whenever a deal field filter or group_by is used (it still counts when neither is).

Request​

Responses​

Aggregation results