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 for specific objects

Last updated May 15, 2023

GET /analytics/v2/reports/:object_type/: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

Get analytics data for specific objects, based on the type of object.

This endpoint is designed around how report data would be shown in the sources report. For more details about how the sources report works, please see the article linked here.

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

Note: Access to the data from this endpoint will depend on the subscription of the 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.
Object type /:object_type
Used in the request URL

The type of object that you want the analytics data for. Must be one of:

  • event-completions - Get data for analytics events. The results are broken down by the event ID. You can get the details for the events using this endpoint.
  • forms - Get data for your HubSpot forms. The results are broken down by form guids. You can get the details for the forms through the Forms API
  • pages - Get data for all URLs with data collected by HubSpot tracking code. The results are broken down by URL. 
  • social-assists - Get data for messages published through the social publishing tools. The results are broken down by the broadcastGuid of the messages. You can get the details of those messages through the Social Media API.
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
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.