The Analytics API allows you to export analytics and reporting data from HubSpot. It’s primarily used to connect metrics tracked in HubSpot to those stored in other business intelligence tools. 

Use case for this API: You're using HubSpot’s blogging and landing page tools, but not the CRM. You want to see the traffic and leads tracked in HubSpot next to the sales activity and deal progression from your CRM to get a fuller sense of your business performance. You use the Analytics API to integrate HubSpot's reporting data with your CRM.

Using the analytics data

The Analytics API is designed around the functionality of HubSpot's various reporting tools. The data returned by these APIs will mimic the data you would see in those tools. For example, when pulling sources data, the results would be similar to what you would see in the sources report.

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.

Many endpoints allow you to drill down into the results using the d1 and d2 parameters. The available drill down options are going to depend on the data being requested. For example, when pulling sources data, the first level drill down options (using the d1 parameter) would be the different source types you'd see in the in the sources report (such as organic, direct, or offline). When drilling down into organic search (d1=organic), the second level drilldown (the d2 parameter) would be a specific keyword, allowing you to get the details for which search engine led to traffic for that specific keyword. When looking for which values you can use for drilling down, it's a good idea to start with the total summary (using total for the :time_period) and looking at the breakdowns in that summary data.

Access to analytics data

Access to data from the Analytics API will depend on the connected HubSpot account's permissions. For example, to pull analytics data for landing pages, the account would need access to create landing pages. To get analytics data broken down by category, the account would need access to the data in the sources report.

Note: All accounts will be able to access certain features of the Analytics API using OAuth based on the table below.

If the account does not have access to the requested data, you will receive a 403 error response. For the full breakdown of the required plan for each feature, see the table below.

Error responses and data limits

The Analytics API limits how much data can be returned in a request. If you exceed those limits, you'll receive one of the following errors:

• 403 response code - The account does not have access to feature required to access this data. See the table above for a full breakdown of the plans required for each feature.
• 413 response code with RESULT_POINT_LIMIT_EXCEEDED - Returned when there are too many time data points. When using a :time_period of daily, weekly, or monthly, the results are limited to 500 time points. Try narrowing the time range between the start and end dates, or using a wider time period (monthly instead of weekly for example).
• 501 response code with RESULT_LIMIT_EXCEEDED - Returned when there are too many breakdowns in the response. When using a total or summarize option for the :time_period, there is a limit of 2 million breakdowns for the response. Try using filters, or removing filters if you're including a large number of filters, or narrowing the time range between the start and end dates.
• 501 response code with SCAN_TIME_EXCEEDED - Returned when the processing time out is hit. Try narrowing the amount of data you're requesting by using filters or narrowing the range between the start and end dates.

Response details

Below you can see examples of responses you'd receive from the Analytics API. The actual stats that you may get are heavily dependent on the data requested. (See the Knowledge Base articles linked above for data descriptions.)

Example data when pulling total stats or stats broken down by specific criteria:

{
  "offset": 6,
  // Integer; Use this value with the 'offset' parameter in the next request to get the next set of results.
  "total": 6,
  // Integer; The total number of results.
  // Offsets are sequential and exclusive (i.e. offset=6 would get you the 7th result), allowing you to use the total results to build a paging footer in your app.
  "totals": {
  // A set of rolled-up stats from all breakdowns.
  // The specific stats will depend on the breakdowns or objects you are getting data for.
    "rawViews": 10709,
    "visits": 4430,
    "visitors": 1779,
    "leads": 956,
    "contacts": 7328,
    "subscribers": 3779,
    "marketingQualifiedLeads": 6,
    "salesQualifiedLeads": 6,
    "opportunities": 1860,
    "customers": 53,
    "pageviewsPerSession": 2.4173814898419863,
    "bounceRate": 0.6419864559819413,
    "timePerSession": 245.64672686230247,
    "newVisitorSessionRate": 0.40158013544018056,
    "sessionToContactRate": 1.654176072234763,
    "contactToCustomerRate": 0.0072325327510917034
  },
  "breakdowns": [
  // A list of stats broken down by the specified criteria or object.
  // The specific stats in each item will depend on the breakdowns or objects you are getting data for.
    {
      "breakdown": "direct",
      // String; The ID for a specific breakdown.
      // These IDs can be used with the 'd1' or 'd2' parameters to further break down the results within a specified breakdown.
      // When pulling data for objects, each breakdown will be the ID of a specific object.
      "rawViews": 8142,
      "visits": 3179,
      "visitors": 1008,
      "leads": 498,
      "contacts": 543,
      "subscribers": 4,
      "opportunities": 39,
      "customers": 2,
      "pageviewsPerSession": 2.5611827618748033,
      "bounceRate": 0.6247247562126454,
      "timePerSession": 296.14878892733566,
      "newVisitorSessionRate": 0.31708084303240014,
      "sessionToContactRate": 0.17080843032400125,
      "contactToCustomerRate": 0.003683241252302026
    },
    {
      "breakdown": "paid",
      "rawViews": 1000,
      "visits": 648,
      "visitors": 604,
      "pageviewsPerSession": 1.5432098765432098,
      "bounceRate": 0.7947530864197531,
      "timePerSession": 45.53086419753087,
      "newVisitorSessionRate": 0.9320987654320988
    },
    {
      "breakdown": "referrals",
      "rawViews": 1526,
      "visits": 567,
      "visitors": 137,
      "contacts": 1,
      "subscribers": 1,
      "pageviewsPerSession": 2.691358024691358,
      "bounceRate": 0.5502645502645502,
      "timePerSession": 205.9241622574956,
      "newVisitorSessionRate": 0.24162257495590828,
      "sessionToContactRate": 0.001763668430335097
    },
    {
      "breakdown": "organic",
      "rawViews": 26,
      "visits": 25,
      "visitors": 21,
      "pageviewsPerSession": 1.04,
      "bounceRate": 0.96,
      "timePerSession": 18.8,
      "newVisitorSessionRate": 0.84
    },
    {
      "breakdown": "other",
      "rawViews": 15,
      "visits": 11,
      "visitors": 9,
      "pageviewsPerSession": 1.3636363636363635,
      "bounceRate": 0.6363636363636364,
      "timePerSession": 2.272727272727273,
      "newVisitorSessionRate": 0.8181818181818182
    },
    {
      "breakdown": "offline",
      "leads": 458,
      "contacts": 6784,
      "subscribers": 3774,
      "marketingQualifiedLeads": 6,
      "salesQualifiedLeads": 6,
      "opportunities": 1821,
      "customers": 51,
      "contactToCustomerRate": 0.007517688679245283
    }
  ]
}

Example data when pulling data for a specific time period (in this case, daily):

// The returned data will be a set of results for each time period (in this case, day).
// Each entry is keyed by the start of the time period in YYYY-MM-DD format.
{
  "2018-01-01": [
  // The start date the specific time period.
  // The specific data in each set will depend on the data being requested.
    {
      "rawViews": 5,
      "visits": 7,
      "visitors": 5,
      "submissions": 2,
      "leads": 2,
      "contacts": 12,
      "subscribers": 10,
      "pageviewsPerSession": 0.7142857142857143,
      "newVisitorSessionRate": 0.7142857142857143,
      "sessionToContactRate": 1.7142857142857142
    }
  ],
  "2018-01-02": [
    {
      "rawViews": 105,
      "visits": 55,
      "visitors": 24,
      "submissions": 16,
      "leads": 7,
      "contacts": 87,
      "subscribers": 76,
      "opportunities": 4,
      "pageviewsPerSession": 1.9090909090909092,
      "newVisitorSessionRate": 0.43636363636363634,
      "sessionToContactRate": 1.5818181818181818
    }
  ],
  "2018-01-03": [
    {
      "rawViews": 163,
      "visits": 105,
      "visitors": 19,
      "submissions": 96,
      "leads": 7,
      "contacts": 120,
      "subscribers": 112,
      "opportunities": 1,
      "pageviewsPerSession": 1.5523809523809524,
      "newVisitorSessionRate": 0.18095238095238095,
      "sessionToContactRate": 1.1428571428571428
    }
  ]
}