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
- 200
- 400
- 401
- 500
Aggregation results
Invalid request parameters
Invalid or missing API key
Internal server error