Skip to main content

Use the reporting API to export analytics and reporting data from HubSpot. Primarily used for connecting HubSpot metrics to metrics stored in other business intelligence tools.

You're hosting your blog on HubSpot while storing CRM data externally, and want to see traffic and leads tracked in HubSpot alongside sales activity in your CRM.

GET

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

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.

Requirements
Scopes
  1. business-intelligence
Auth Methods

Private apps

OAuth

Parameters
breakdown_by*

Path param

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*

Path param

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/weekly - Grouped by week, data is rolled up across all breakdowns
  • summarize/monthly - Grouped 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*

Query param

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*

Query param

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.

d1

Query param

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.

d2

Query param

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.

f

Query param

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.

e

Query param

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.

filterId

Query param

The ID of an Analytics view. If included, the returned data will only include data that matches the view. See this endpoint for details on getting the IDs for the views.

sort

Query param

If included, the results are sorted by the specified field.

sortDir

Query param

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

Query param

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

Query param

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.

Response

Show more

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.

GET

/analytics/v2/reports/:object_type/:time_period

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.

Requirements
Scopes
  1. business-intelligence
Auth Methods

Private apps

OAuth

Parameters
object_type*

Path param

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*

Path param

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/weekly - Grouped by week, data is rolled up across all breakdowns
  • summarize/monthly - Grouped 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*

Query param

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*

Query param

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.

d1

Query param

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.

d2

Query param

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.

f

Query param

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.

e

Query param

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.

filterId

Query param

The ID of an Analytics view. If included, the returned data will only include data that matches the view. See this endpoint for details on getting the IDs for the views.

sort

Query param

If included, the results are sorted by the specified field.

sortDir

Query param

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

Query param

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

Query param

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.

Response

Show more

GET

/analytics/v2/reports/:content_type/:time_period

Get analytics data for your HubSpot hosted content. This would include your website and landing pages, as well as any blog pages hosted on HubSpot.

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

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

In addition to getting analytics details for pages, sources data can also be pulled for pages or for blogs: For pages: GET analytics/v2/reports/:content_type/:page_id/sources/:time_period

For blogs: GET analytics/v2/reports/:content_type/content-group/:blog_id/sources/:time_period

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.

Requirements
Scopes
  1. business-intelligence
Auth Methods

Private apps

OAuth

Parameters
content_type*

Path param

The type of content that you want to get data for. Must be one of:

  • landing-pages - Pull data for landing pages.
  • standard-pages - Pull data for website pages.
  • blog-posts - Pull data for individual blog posts.
  • listing-pages - Pull data for blog listing pages.
  • knowledge-articles - Pull data for knowledge base articles.
:page_id/ sources*

Path param

A page ID can be included the URL to get sources data for a specific page. See the examples for details.

/content-group/ :blog_id/ sources*

Path param

A blog ID can be specified to get data for all content related to a specific blog. The content_type must be blog-posts or listing-pages, see the examples for details.

time_period*

Path param

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/weekly - Grouped by week, data is rolled up across all breakdowns

  • summarize/monthly - Grouped 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*

Query param

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*

Query param

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.

d1

Query param

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.

d2

Query param

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.

f

Query param

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.

e

Query param

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.

filterId

Query param

The ID of an Analytics view. If included, the returned data will only include data that matches the view. See this endpoint for details on getting the IDs for the views.

sort

Query param

If included, the results are sorted by the specified field.

sortDir

Query param

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

Query param

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

Query param

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.

Response

Show more

Check for the existence of analytics data for an object type

GET

/analytics/v2/reports/:objectType/exists

Check to see if there is analytics data for a specified object type. This can be used to perform a simple, quick check to see if a HubSpot account has any analytics data for the specified object type.

The response is a simple "exists": true if there is data, or "exists": false if there is no data for the object type.

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.

Requirements
Scopes
  1. business-intelligence
Auth Methods

Private apps

OAuth

Parameters
objectType*

Path param

The object type that you want to check for analytics data. See the table below for the supported object types.

Response

Show more

GET

/reports/v2/events/:id

Given an event ID, returns a specific event definition in a given portal. Events can be created in-app, or dynamically via the Tracking Code API.

Requirements
Scopes
  1. business-intelligence
Auth Methods

Private apps

OAuth

Parameters
id*

Path param

The ID of the specific event you're looking to pull.

includeDeletes

Query param

If specified as true, will return a deleted event. Otherwise, requesting deleted events by ID will return a 404.

Response

Show more

GET

/reports/v2/events

This endpoint is used to get data for all events in a HubSpot account with a Marketing Hub Enterprise subscription. Events can be created in-app or dynamically via the Tracking Code API.

Use case for this endpoint: You can use this method to retrieve all event definitions and confirm data is syncing with an external analytics solution.

Requirements
Scopes
  1. business-intelligence
Auth Methods

Private apps

OAuth

Parameters
includeDeletes

Query param

If specified as true, include deleted events

Response

Show more

Returns all of the event definitions in a given portal.

Note: Access to the data from this endpoint will require a Marketing Hub Enterprise subscription. Please see the Analytics API Overview for more details.

GET

/reports/v2/events/batch

Given a batch of event IDs, returns a list of event definitions in a given portal. Events can be created in-app, or dynamically via the Tracking Code API.

Note: Access to the data from this endpoint will require a Marketing Hub Enterprise subscription. Please see the overview page for more details.

Requirements
Scopes
  1. business-intelligence
Auth Methods

Private apps

OAuth

Parameters
id*

Query param

The ID of an event. Can be included multiple times to pull multiple events.

includeDeletes

Query param

If specified as true, will include deleted events.

Response

Show more

GET

/analytics/v2/views

Get the details for the analytics views set up in the portal. The id of a view can be used to filter the data from the Analytics API endpoints using the filterId= query parameter.

Note: Access to the data from this endpoint will require a Marketing Hub Professional or Enterprise subscription. Please see the overview page for more details.

Requirements
Scopes
  1. business-intelligence
Auth Methods

Private apps

OAuth

Parameters

This endpoint doesn't take any parameters.

Response

Show more