> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: 8f08221c-facd-4a02-87bd-f76aac99bb34
---
# Get statistics histogram
> Get aggregated statistics in intervals for a specified time span. Each interval contains aggregated statistics of the emails that were sent in that time.
export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
;
};
## OpenAPI
````yaml specs/2026-03/marketing-marketing-emails-v2026-03.json GET /marketing/emails/2026-03/statistics/histogram
openapi: 3.0.1
info:
title: Marketing Emails
description: Basepom for all HubSpot Projects
version: 2026-03
x-hubspot-product-tier-requirements:
marketing: FREE
sales: FREE
service: FREE
cms: FREE
commerce: FREE
crmHub: FREE
dataHub: FREE
x-hubspot-api-use-case: >-
You want to programmatically create marketing emails, then retrieve their
send statistics at a later time.
x-hubspot-introduction: >-
Use the marketing email API to create, manage, and retrieve details about
marketing emails. You can also this use API to retrieve statistics related
to email sends, similar to what you can see in HubSpot.
servers:
- url: https://api.hubapi.com
security: []
tags:
- name: Basic
- name: Emails
paths:
/marketing/emails/2026-03/statistics/histogram:
get:
tags:
- Basic
summary: Get aggregated statistic intervals
description: >-
Get aggregated statistics in intervals for a specified time span. Each
interval contains aggregated statistics of the emails that were sent in
that time.
operationId: get-/marketing/emails/2026-03/statistics/histogram_getHistogram
parameters:
- name: emailIds
in: query
description: >-
Filter by email IDs. Only include statistics of emails with these
IDs.
required: false
style: form
explode: true
schema:
type: array
items:
type: integer
format: int64
- name: endTimestamp
in: query
description: The end timestamp of the time span, in ISO8601 representation.
required: false
style: form
explode: true
schema:
type: string
format: date-time
- name: interval
in: query
description: The interval to aggregate statistics for.
required: false
style: form
explode: true
schema:
type: string
enum:
- DAY
- HOUR
- MINUTE
- MONTH
- QUARTER
- QUARTER_HOUR
- SECOND
- WEEK
- YEAR
- name: startTimestamp
in: query
description: The start timestamp of the time span, in ISO8601 representation.
required: false
style: form
explode: true
schema:
type: string
format: date-time
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: >-
#/components/schemas/CollectionResponseWithTotalEmailStatisticInterval
default:
$ref: '#/components/responses/Error'
description: ''
security:
- oauth2:
- content
components:
schemas:
CollectionResponseWithTotalEmailStatisticInterval:
required:
- results
- total
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
results:
type: array
items:
$ref: '#/components/schemas/EmailStatisticInterval'
total:
type: integer
format: int32
Paging:
type: object
properties:
next:
$ref: '#/components/schemas/NextPage'
prev:
$ref: '#/components/schemas/PreviousPage'
EmailStatisticInterval:
required:
- aggregations
- interval
type: object
properties:
aggregations:
$ref: '#/components/schemas/EmailStatisticsData'
interval:
$ref: '#/components/schemas/Interval'
Error:
required:
- category
- correlationId
- message
type: object
properties:
category:
type: string
description: The error category
context:
type: object
additionalProperties:
type: array
items:
type: string
description: Context about the error condition
example: >-
{invalidPropertyName=[propertyValue], missingScopes=[scope1,
scope2]}
correlationId:
type: string
description: >-
A unique identifier for the request. Include this value with any
error reports or support tickets
format: uuid
example: aeb5f871-7f07-4993-9211-075dc63e7cbf
errors:
type: array
description: further information about the error
items:
$ref: '#/components/schemas/ErrorDetail'
links:
type: object
additionalProperties:
type: string
description: >-
A map of link names to associated URIs containing documentation
about the error or recommended remediation steps
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate
example: An error occurred
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error
example:
message: Invalid input (details will vary based on the error)
correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
category: VALIDATION_ERROR
links:
knowledge-base: https://www.hubspot.com/products/service/knowledge-base
NextPage:
required:
- after
type: object
properties:
after:
type: string
description: >-
The cursor token value to get the next set of results. Use this
value as query parameter (&after=...) to obtain the next page.
link:
type: string
description: The link to the next page.
description: >-
Specifies the paging information needed to retrieve the next set of
results in a paginated API response
PreviousPage:
required:
- before
type: object
properties:
before:
type: string
description: >-
The cursor token value to get the previous set of results. Use this
value as query parameter (&before=...) to obtain the previous page.
link:
type: string
description: The link to the previous page.
description: >-
specifies the paging information needed to retrieve the previous set of
results in a paginated API response
EmailStatisticsData:
required:
- counters
- deviceBreakdown
- qualifierStats
- ratios
type: object
properties:
counters:
type: object
additionalProperties:
type: integer
format: int64
description: Counters like number of `sent`, `open` or `delivered`.
deviceBreakdown:
type: object
additionalProperties:
type: object
additionalProperties:
type: integer
format: int64
description: Statistics by device.
qualifierStats:
type: object
additionalProperties:
type: object
additionalProperties:
type: integer
format: int64
description: Number of emails that were dropped and bounced.
ratios:
type: object
additionalProperties:
type: number
description: Ratios like `openratio` or `clickratio`
Interval:
required:
- end
- start
type: object
properties:
end:
type: string
description: The end timestamp of the interval, in ISO8601 format.
format: date-time
start:
type: string
description: The start timestamp of the interval, in ISO8601 format.
format: date-time
ErrorDetail:
required:
- message
type: object
properties:
code:
type: string
description: The status code associated with the error detail
context:
type: object
additionalProperties:
type: array
items:
type: string
description: Context about the error condition
example: '{missingScopes=[scope1, scope2]}'
in:
type: string
description: The name of the field or parameter in which the error was found.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error
responses:
Error:
description: An error occurred.
content:
'*/*':
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://app.hubspot.com/oauth/authorize
tokenUrl: https://api.hubapi.com/oauth/v1/token
scopes:
content: ''
transactional-email: ''
````
{product.name} -
{product.level}
)}