Reporting
This is a stable API but uses an older format. This means some functionality may not be available (for example test calls and Postman integration).
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
Parameters
totals
- Data will be the totals rolled up fromsessions
- Data broken down by session detailssources
- Data broken down by traffic sourcegeolocation
- 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 ofcampaigns
,contents
,mediums
,sources
, orterms
(i.e.utm-campaigns
).
total
- Data is rolled up to totals covering the specified time.daily
- Grouped by dayweekly
- Grouped by weekmonthly
- Grouped by monthsummarize/daily
- Grouped by day, data is rolled up across all breakdownssummarize/weekly
- Grouped by week, data is rolled up across all breakdownssummarize/monthly
- Grouped by month, data is rolled up across all breakdowns
&f=
parameter). See below for details.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.
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.
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.
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.
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
.
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
.
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.
If included, the results are sorted by the specified field.
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.
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
.
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
NOTE: All examples get data between Jan 1 2018 and Mar 1 2018:
&start=20180101&end=20180301
Example URLs:
Get the totals across all metrics:
https://api.hubapi.com/analytics/v2/reports/totals/total?start=20180101&end=20180301
Get a summary of all traffic for each day:
https://api.hubapi.com/analytics/v2/reports/totals/summarize/daily?start=20180101&end=20180301
Get a weekly breakdown of data for visitor sessions
(including things like bounce rate and time per session):
https://api.hubapi.com/analytics/v2/reports/sessions/weekly?start=20180101&end=20180301
Get the summary of all traffic broken down by source:
https://api.hubapi.com/analytics/v2/reports/sources/total?start=20180101&end=20180301
Get a daily breakdown of visits from Twitter:
https://api.hubapi.com/analytics/v2/reports/sources/daily?start=20180101&end=20180301&d1=social&f=Twitter
Get a breakdown of all vists based on geographic location:
https://api.hubapi.com/analytics/v2/reports/geolocation/total?start=20180101&end=20180301
Get a monthly breakdown of visits from Germany ('de') and Ireland ('ie'):
https://api.hubapi.com/analytics/v2/reports/geolocation/monthly?start=20180101&end=20180301&f=de&f=ie
Get a summary of all visits across all campaigns (anything included in the utm_campaign parameter):
https://api.hubapi.com/analytics/v2/reports/utm-campaigns/total?start=20180101&end=20180301
Get a weekly summary of visits to the 'test' campaign (utm_campaign=test):
https://api.hubapi.com/analytics/v2/reports/utm-campaigns/summarize/weekly?start=20180101&end=20180301&d1=test
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
Parameters
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 formguids
. 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.
total
- Data is rolled up to totals covering the specified time.daily
- Grouped by dayweekly
- Grouped by weekmonthly
- Grouped by monthsummarize/daily
- Grouped by day, data is rolled up across all breakdownssummarize/weekly
- Grouped by week, data is rolled up across all breakdownssummarize/monthly
- Grouped by month, data is rolled up across all breakdowns
&f=
parameter). See below for details.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.
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.
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.
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.
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
.
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
.
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.
If included, the results are sorted by the specified field.
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.
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
.
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
xxxxxxxxxx
NOTE: All examples get data between Jan 1 2018 and Mar 1 2018:
&start=20180101&end=20180301
Example URLs:
Get a summary for all of your forms:
https://api.hubapi.com/analytics/v2/reports/forms/total?start=20180101&end=20180301
Get a daily breakdown for a specific form (with guid '7ca1364a-500a-4581-a677-29301f402ef2'):
https://api.hubapi.com/analytics/v2/reports/forms/daily?&start=20180101&end=20180301&f=7ca1364a-500a-4581-a677-29301f402ef2
Get the details for the 5 forms with the most submissions:
https://api.hubapi.com/analytics/v2/reports/forms/total?start=20180101&end=20180301&sort=submissions&limit=5
Get a summary of analytics data collected by the HubSpot tracking code, broken down by page URL:
https://api.hubapi.com/analytics/v2/reports/pages/total?start=20180101&end=20180301
Get a summary of the page data, broken down by day:
https://api.hubapi.com/analytics/v2/reports/pages/summarize/daily?start=20180101&end=20180301
Get the weekly breakdown for a specific page with the UR 'developers.hubspot.com/':
https://api.hubapi.com/analytics/v2/reports/pages/weekly?start=20180101&end=20180301&f=developers.hubspot.com%2F
Get the top 5 pages with the highest average time per pageview:
https://api.hubapi.com/analytics/v2/reports/pages/total?start=20180101&end=20180301&limit=5&sort=timePerPageview
Get the top 5 pages with the highest number of entrances (where the page was the first viewed in a session),
but exclude the home page with the URL 'www.hubspot.com/':
https://api.hubapi.com/analytics/v2/reports/pages/total?start=20180101&end=20180301&limit=5&sort=entrances&e=www.hubspot.com%2F
Get a summary of data for all social media messages:
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
Parameters
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.
A page ID can be included the URL to get sources data for a specific page. See the examples for details.
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.
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 dayweekly
- Grouped by weekmonthly
- Grouped by monthsummarize/daily
- Grouped by day, data is rolled up across all breakdownssummarize/weekly
- Grouped by week, data is rolled up across all breakdownssummarize/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.
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.
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.
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.
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.
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
.
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
.
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.
If included, the results are sorted by the specified field.
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.
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
.
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
xxxxxxxxxx
NOTE: All examples get data between Jan 1 2018 and Mar 1 2018:
&start=20180101&end=20180301
Example URLs:
Get a summary of data for all HubSpot website pages:
https://api.hubapi.com/analytics/v2/reports/standard-pages/total?start=20180101&end=20180301
Get a daily summary for all landing pages:
https://api.hubapi.com/analytics/v2/reports/landing-pages/summarize/daily?start=20180101&end=20180301
Get a daily breakdown for a specific website page with ID 5525553014:
https://api.hubapi.com/analytics/v2/reports/standard-pages/daily?start=20180101&end=20180301&f=5525553014
Get a summary of sources data for a specific landing page with ID 5507681239:
https://api.hubapi.com/analytics/v2/reports/landing-pages/5507681239/sources/total?start=20180101&end=20180301
Get breakdown of organic keywords that led to traffic for a specific website page:
https://api.hubapi.com/analytics/v2/reports/standard-pages/5525553014/sources/total?start=20180101&end=20180301&d1=organic
Get a summary of the top 10 blog posts by entrances (the page was the first page viewed in a session):
https://api.hubapi.com/analytics/v2/reports/blog-posts/total?start=20180101&end=20180301&sort=entrances&limit=10
Get a breakdown of organic keywords that lead to traffic for all blog posts in the blog with ID 351076997
https://api.hubapi.com/analytics/v2/reports/blog-posts/content-group/351076997/sources/total?start=20180101&end=20180201&d1=organic
Example Response:
{
"offset": 3,
"total": 11,
Check for the existence of analytics data for an object type
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
Parameters
The object type that you want to check for analytics data. See the table below for the supported object types.
Response
xxxxxxxxxx
Example GET URL:
https://api.hubapi.com/analytics/v2/reports/event-completions/exists
Example response:
{
"exists": true
}
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
Parameters
The ID of the specific event you're looking to pull.
If specified as true, will return a deleted event. Otherwise, requesting deleted events by ID will return a 404.
Response
xxxxxxxxxx
Example request URL:
https://api.hubapi.com/reports/v2/events/000000142311
Example response:
{
"id": "000000142311",
"name": "Neilsdja",
"label": null,
"status":"ACTIVE"
}
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
Parameters
If specified as true
, include deleted events
Response
xxxxxxxxxx
Example request URL:
https://api.hubapi.com/reports/v2/events
Example response:
[
{
"id": "000000142311",
"name": "Neilsdja",
"label": null,
"status":"ACTIVE"
},
{
"id": "000000142312",
"name": "dsasd",
"label": null,
"status":"ACTIVE"
},
{
"id": "000000142313",
"name": null,
"label": "neil",
"status":"ACTIVE"
},
{
"id": "000000142314",
"name": null,
"label": "greate",
"status":"ACTIVE"
},
{
"id": "000000142321",
"name": null,
"label": "justforfun",
"status":"ACTIVE"
},
{
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
Parameters
The ID of an event. Can be included multiple times to pull multiple events.
If specified as true, will include deleted events.
Response
xxxxxxxxxx
Example request URL:
https://api.hubapi.com/reports/v2/events/batch?id=000000142311&id=000000142312
Example response:
[
{
"id": "000000142311",
"name": "Neilsdja",
"label": null,
"status":"ACTIVE"
},
{
id:"000000142312",
name:"dsasd",
label:null,
"status":"ACTIVE"
}
]
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
Parameters
Response
xxxxxxxxxx
Example request URL:
https://api.hubapi.com/analytics/v2/views
Example response:
[
{
"title": "Big Data Blog Posts",
"updaterId": 212412,
"updatedDate": "2018-08-07",
"creatorId": 212412,
"containsLegacyReportProperties": true,
"deletedAt": 0,
"reportPropertyFilters": [
{
"op": "STARTS_WITH",
"args": [
"https://www.biglytics.net/blog/topic/big-data"
],
"prop": "URL"
}
],
"id": 131,
"createdAt": 1533665528459
},
{
"title": "Traffic from U.S.",
"updaterId": 852173,
"updatedDate": "2018-08-09",
"creatorId": 852173,
"containsLegacyReportProperties": false,
"deletedAt": 0,
"reportPropertyFilters": [
{
"op": "IS",
"args": [
"us"