New Analytics API Limitations


The business-intelligence scope for the Analytics API says that it has limited functionality for accounts without a paid Marketing subscription. What exactly does "limited functionality" mean? And will free Marketing subscriptions ever have full functionality?

Also, how are we expected to convert times from UTC to the portal's time zone when passing in dates for the "start" and "end" request parameters? I know we can use the "GET /integrations/v1/me" endpoint to get their time zone but that is not a valid string for conversion. Is there a list of all possible time zones your API could return so I can make my own conversion table?


Hi @Wes_Thompson,

'Limited functionality' means that portals without a paid marketing subscription won't have access to aspects of the Analytics API that correspond to tools only present in portals with a paid marketing subscription. A basic example is that a portal without a paid marketing subscription would not be able to access data on HubSpot hosted content or social media messages, since they don't have access to those tools.

Regarding timezones: We return the Java timezone ID; you can find a list of all possible values here:

That said, I can completely understand the difficulty of implementing your own conversion table. I'll talk to my team and see if we can adjust the information returned by the /integrations/v1/me endpoint. I'll reach out here once I have an update on that front.


That is wonderful to hear thank you so much.

While I have you, I have a couple more questions.

Some of the breakdowns do not allow the use of the summarize/daily time period. When I use the regular daily time period it requires a filter. I've found out that using a filter of an empty string seems like it returns everything. If that is true, then why is the filter required at all?

Also, I am using the demo hapikey for testing this API and the responses do not seem standard for each breakdown. For instance, when I break down by session I get a list of objects where the breakdown field is actually the metric (like time-per-session) and the other values are what actually seem like breakdowns (such as mobile device and desktop). When I use the source breakdown it returns a list of objects with a bunch of metrics in them but no breakdown field. And when I breakdown by any of the utm- fields I get an empty object back. And just to be clear I am querying all of these using the summarize/daily or daily time period.

So first of all, are the responses like the sources breakdown, is the breakdown missing on purpose? Or am I possibly doing something wrong?

Also, the values from the session breakdown feel a little backwards to me. I would expect "mobile" or "desktop" to be the breakdown value with a list of metrics related to it.

And lastly, your example in the documentation looks like it's using utm-campaign but I am only getting empty objects back when I use it with the summarize/daily time period. (EDIT: it looks like it's only empty for certain dates)

I feel like if all these different responses are intended then they should be documented.


Hi @Wes_Thompson,

I'll try to address your questions individually:

  1. The &filter= parameter is listed as optional, so it shouldn't be required. Do you see errors when you exclude it?
  2. The demo hapikey returns data from the HubSpot Developer demo portal, so it's not necessarily going to reflect exactly what you would see. If a breakdown by utm fields returns an empty object, it's likely that data doesn't exist in the demo portal. In these cases, it might be best to test it out on a live portal (where you know the data exists) to see what the actual responses look like. To know for sure if the demo portal is missing data or if your request is malformed somehow, I'd need to take a closer look at the exact request you're making.


The documentation says one or more filter is required when using a daily, weekly, or monthly time_period. To avoid this requirement I was using summarize/daily time_period. However, when I make that request with the sessions breakdown I get this error:

Unable to summarize session metrics because they're discrete datasets

When I switch the time period to daily instead of trying to summarize it, it seems to work for sessions. If I change the breakdown to sources however, I get this error:

Filters are required for queries by points

Then if I switch the time_period back to summarize/daily it seems to work for the sources breakdown. However, it does not return the breakdown field in each object (
Why would it not return the breakdown in each object like it does with sessions?


Hi @Wes_Thompson,

So there are a couple things to unpack here. First, the sessions breakdown can't be summarized; they're separate metrics that can't be combined. Second, it's not possible to just pull everything; the reason we require a filter is because the results mirror the sources report in-app. The API is intended to return specific, unique data sets, as opposed to large, general data sets. This is also the reason that the objects returned differ from one another; different requests produce entirely different sets of data, which are structured differently.

I'll touch base with the team regarding better documenting the different types of responses/requests. I think this is a situation where how-to guides or other more thorough examples could be useful.


First I'd like to say thank you for all the good information. This has been very helpful.

Now I'm trying to test our integration with a free Marketing account which you said has limited functionality based on the tools of the Analytics API that correspond to tools that they would normally have access to. Whenever I try to query the Analytics API I get this error

This oauth-token does not have proper permissions! (requires all of [traffic-analytics-api-access])

I was authorizing the "business-intelligence" scope and I have tried adding the other scopes that free Marketing accounts have access to (such as "contacts", "files", and "timeline") but I keep getting the same error for each endpoint. My current access token has all four of those scopes and it is returning the same error. What am I missing to be able to access any sort of information with a free Marketing account?


Hi @Wes_Thompson,

I'm not entirely sure here; let me dig into this with my team. I'll update this thread when I have more information related to this issue.

Minimal users plan to use APP with "reports" scope
Missing IDs from Forms and Blog Posts

Did you ever get any more information on this? I still can't seem to use the Analytics API with free accounts at all.


Hi @Wes_Thompson,

Sorry about the delay here; this post flew completely under my radar. The tl;dr here is that in order to have access to a particular method of the Analytics API, the portal in question needs to have access to the corresponding tool in HubSpot. This can be broken down in the following ways:

  • Much of the data is going to require access to the sources report, so it will be included with a Basic, Pro, or Enterprise Marketing account.
    • This would include data provided by the GET /analytics/v2/reports/:breakdown_by/:time_period endpoint and pages data from the GET /analytics/v2/reports/:object_type/:time_period endpoint.
  • The social-assets data would also require the same level of paid marketing accounts, since that data is based on access to the social media tools.
  • Analytics data for HubSpot hosted content would require access to the relevant content hosting access (website pages, landing pages, knowledge base articles, etc.).
    • This would generally be a Marketing Basic subscription for most content types, but would require Service Hub for knowledge base articles.
  • All plans include access to get analytics data for forms, as all plans have some level of access to forms and reporting in HubSpot.

Let me know if you have any other questions!