There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Get analytics data breakdowns

Last updated May 15, 2023

GET /analytics/v2/reports/:breakdown_by/:time_period

Method Details

HTTP Methods:

GET

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

Required Scope:

business-intelligence

This endpoint is used to get analytics data for a specified category.

Use case for this endpoint: This endpoint is designed to mimic how report data is shown in a sources report. You can use it to pass website traffic data tracked in HubSpot to external business intelligence (BI) tools.

For more details about how sessions are categorized, please see the article linked here.

Response details

For information about the error messages you can get from this endpoint, please see the overview page.

Note: Access to the data requested using this endpoint will depend on the subscription of the connected HubSpot account. Please see the overview page for more details.

Required parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
Breakdown by /:breakdown_by
Used in the request URL

The category used to break down the analytics data. Must be one of:

  • totals - Data will be the totals rolled up from 
  • sessions - Data broken down by session details 
  • sources - Data broken down by traffic source
  • geolocation - Data broken down by geographic location. Locations are formatted as ISO 3166-1 alpha-2 country codes.
  • utm-:utm_type - Data broken down by the standard UTM parameters. :utm_type must be one of campaigns, contents, mediums, sources, or terms (i.e. utm-campaigns).
Time period /:time_period
Used in the request URL

The time period used to group the data. Must be one of:

  • total - Data is rolled up to totals covering the specified time.
  • daily - Grouped by day
  • weekly - Grouped by week
  • monthly - Grouped by month
  • summarize/daily - Grouped by day, data is rolled up across all breakdowns 
  • summarize/weeklyGrouped by week, data is rolled up across all breakdowns 
  • summarize/monthlyGrouped by month, data is rolled up across all breakdowns

NOTE: When using daily, weekly, or monthly for the time_period, you must include at least one filter (&f= parameter). See below for details.

Start date 

&start=YYYYMMDD
Used in the request URL.

The start date for the data you want. Must be included as ISO 8601 format, YYYYMMDD. Note: The date is inclusive, and will be treated as being in the time zone of the portal.
End date

&end=YYYYMMDD
Used in the request URL.

The end date for the data you want. Must be included as ISO 8601 format, YYYYMMDD. Note: The date is inclusive, and will be treated as being in the time zone of the portal.

Optional parameters How to use Description
First drilldown &d1=
Used in the request URL
Used to drilldown into the data. This parameter is designed to reflect the functionality of the HubSpot sources reports. For example, when breaking down by sources, d1 could be organic to drill down into organic traffic data.

Note
: Starter plans will not be able to use the &d1= or &d2= drilldown parameters.
Second drilldown &d2=
Used in the request URL
Used to further drill down into the data. Similar to d1, this reflects the functionality of the sources report. For example, if you have d1=organic, d2=hubspot would drill down into data for organic search traffic for the keyword `hubspot`.

Note
: Starter plans will not be able to use the &d1= or &d2= drilldown parameters.
Filter &f=
Used in the request URL.
May be included multiple times.
Filter the returned data to include only the specified breakdown. This parameter can be included multiple times to filter for multiple breakdowns. For example, when breaking down by sources and using d1=organic to drill down into organic search traffic, you can get the data for the specific keywords `hubspot` and `marketing` using f=hubspot&f=marketing.

NOTE: You must include at least 1 filter when the :time_period is monthly, weekly, or daily.
Exclude &e=
Used in the request URL.
May be included multiple times.
Exclude data for the specified breakdown. This parameter can be included multiple times to exclude multiple breakdowns.For example, when breaking down by sources and using d1=referrals to drill down into referral traffic, you can exclude data for referral traffic from 'www.hubspot.com' by using e=www.hubspot.com.
Analytics View ID &filterId=
Used in the request URL
The ID of an Analytics view. If included, the returned data will only include data that matches the view. See this page for details on getting the IDs for the views.
Sort by sort=
Used in the request URL.
If included, the results are sorted by the specified field.
Sort direction &sortDir=
Used in the request URL.
If a &sort= value is included in the request, this parameter will control the direction of sorted results. Must be one of ASC (ascending) or DESC (descending). Defaults to DESC if not included.
Limit &limit=
Used in the request URL
Used to limit the number of results per request. If included, the response will include an offset value that can be used to get the next page or results. Defaults to 350 if not included.

NOTE: This parameter will be ignored if the :time_period is monthly, weekly, or daily.
Offset &offset=
Used in the request URL

Used to get the next page of results if there are more results than the number specified in the limit parameter (or 350 if limit is not included). Each response will include an offset field, and you can use the response value in the offset parameter in the next request to get the next set of results.