Using the Analytics API

The Analytics API allows you to pull detailed marketing performance data from your HubSpot account.

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 data in 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 requests. 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.

Error responses and data limits

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

  • 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.

Example data

Below you can see examples of the structure of data you'd receive from the Analytics API. The actual stats that you may get are heavily dependent on the data being requested. See the knowledge base articles linked above for descriptions of the data.

Example data when pulling total stats or stats broken down by a 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
    }
  ]
}

Docs for this section or API