Get metrics for your contacts based on their lifecycle stage



What’s happening?

Today, we’re releasing a new endpoint that will allow you to pull metrics based on the lifecycle stage of your contacts. These metrics will show you the number of contacts that entered each lifecycle stage over the course of a specified time. The metrics can be further aggregated by any enumerated property, including Original Source (hs_analytics_source). You can find more details in the documentation here.

Why is this important?

This would allow you, for example, to get the metrics for the number of new leads and customers over the last 30 days, and break down those records by their source, allowing users of your integration to see the number of new customers that had a source of Organic Search.

Your integration could also display these metrics based on any enumerated property, including any custom enumerated properties that your integration may create.

When is this happening?

This endpoint is available now. The endpoint requires the contacts scope, so if your integration is already working with contacts you’d be able to start using this endpoint without needing your users to re-authorize your integration.

Please reply to this thread if you have any questions about this new endpoint.


Awesome. Thanks for making this available, HubSpot.

We're leveraging this new API here:



I am currently using this endpoint to get monthly contact metrics by a property hs_lead_status

Am I able to add another property hubspot_team_id to be able to get further breakdown of the metrics by Hubspot team or even by Hubspot owner?

Any assistance in providing this information is greatly appreciated.


Hi @arnoldmarunda,

At this time, only one aggregation property is supported per request to this endpoint.

That said, you could create lists using the Became a [lifecycle stage] date properties:

and then use either of these Contact Lists API endpoints to retrieve similar data:

This approach affords more flexibility for multiple breakdowns.