> ## 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.
# Search reports
> Searches for and returns pages of reports using a variety of filters. Search is eventually-consistent; changes to dashboards may take a few seconds to reflect in search results.
Also supports retrieving pages of archived reports; however, the following restrictions apply: only the `limit` and `after` parameters are respected, all others are ignored; archived report retrieval does not support filtering, custom sorting, or property projection. Results are always returned in order from most recently deleted to least recently deleted.
export const UserLevelAccessCallout = () =>
;
};
## OpenAPI
````yaml specs/2027-03-beta/analytics-reporting-v2027-03-beta.json GET /analytics/reporting/2027-03-beta/reports
openapi: 3.0.1
info:
title: Analytics Reporting
description: Basepom for all HubSpot Projects
version: 2027-03-beta
x-hubspot-product-tier-requirements:
marketing: FREE
sales: FREE
service: FREE
cms: FREE
commerce: FREE
crmHub: FREE
dataHub: FREE
servers:
- url: https://api.hubapi.com
security: []
tags:
- name: Dashboards
- name: Reports
paths:
/analytics/reporting/2027-03-beta/reports:
get:
tags:
- Reports
summary: Search reports
description: >-
Searches for and returns pages of reports using a variety of filters.
Search is eventually-consistent; changes to dashboards may take a few
seconds to reflect in search results.
Also supports retrieving pages of archived reports; however, the
following restrictions apply: only the `limit` and `after` parameters
are respected, all others are ignored; archived report retrieval does
not support filtering, custom sorting, or property projection. Results
are always returned in order from most recently deleted to least
recently deleted.
operationId: get-/analytics/reporting/2027-03-beta/reports
parameters:
- name: after
in: query
description: >-
A cursor token for pagination. Use the value from the previous
response's paging.next.after field.
required: false
style: form
explode: true
schema:
type: string
- name: archived
in: query
description: Whether to retrieve archived reports only. Default false.
required: false
style: form
explode: true
schema:
type: boolean
- name: businessUnitIds
in: query
description: Filter to reports that are a part of the specified business units.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: createdAfter
in: query
description: Filter to reports created after a specific date and time.
required: false
style: form
explode: true
schema:
type: string
format: date-time
- name: createdBefore
in: query
description: Filter to reports created before a specific date and time.
required: false
style: form
explode: true
schema:
type: string
format: date-time
- name: dashboardId
in: query
description: Filter to reports on the specified dashboard.
required: false
style: form
explode: true
schema:
type: string
- name: ids
in: query
description: Filter to reports with the specified IDs.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: limit
in: query
description: >-
The maximum number of results to display per page. Default 25, max
100.
required: false
style: form
explode: true
schema:
type: integer
format: int32
- name: onDashboard
in: query
description: >-
Filter to reports that are on, or not on, any dashboard. Unset by
default.
required: false
style: form
explode: true
schema:
type: boolean
- name: onlyFavorites
in: query
description: >-
Filter to only reports that are favorited by the requesting user.
Default false.
required: false
style: form
explode: true
schema:
type: boolean
- name: ownerUserIds
in: query
description: Filter to reports owned by the specified users.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: properties
in: query
description: >-
Additionally properties to include in the response. Refer to the
response details for available fields.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: q
in: query
description: >-
Filter to reports whose name or description contains the search
string.
required: false
style: form
explode: true
schema:
type: string
- name: sort
in: query
description: >-
Sort field and direction. Supported fields are `name`, `updatedAt`,
and `lastViewedAt`. Defaults to `-updatedAt`
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: tagIds
in: query
description: Filter to reports tagged with the specified tags.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: updatedAfter
in: query
description: Filter to reports updated after a specific date and time.
required: false
style: form
explode: true
schema:
type: string
format: date-time
- name: updatedBefore
in: query
description: Filter to reports updated before a specific date and time.
required: false
style: form
explode: true
schema:
type: string
format: date-time
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionResponseWithTotalPublicReport'
default:
$ref: '#/components/responses/Error'
description: ''
security:
- oauth2:
- reporting.full.read
- oauth2:
- reporting.full.admin
- oauth2:
- crm.hubsql.execute
components:
schemas:
CollectionResponseWithTotalPublicReport:
required:
- results
- total
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
results:
type: array
description: An array of report objects.
items:
$ref: '#/components/schemas/PublicReport'
total:
type: integer
description: The total number of reports available.
format: int32
Paging:
type: object
properties:
next:
$ref: '#/components/schemas/NextPage'
prev:
$ref: '#/components/schemas/PreviousPage'
description: >-
Represents the pagination information for navigating through a list of
results in the API. It provides details on how to access the previous or
next set of results.
PublicReport:
required:
- archived
- businessUnitId
- createdAt
- id
- name
- updatedAt
type: object
properties:
archived:
type: boolean
description: Whether the report is archived.
archivedAt:
type: string
description: >-
If the report is archived, the date and time when the report was
archived, in ISO 8601 format. Absent if the report is not archived.
format: date-time
businessUnitId:
type: string
description: The ID of the business unit that the report is associated with.
createdAt:
type: string
description: The date and time when the report was created, in ISO 8601 format.
format: date-time
createdByUserId:
type: string
description: The ID of the user who created the report. May be absent.
description:
type: string
description: A description of the report. May be absent.
id:
type: string
description: The ID of the report.
lastViewedAt:
type: string
description: >-
The date and time when the report was last viewed, in ISO 8601
format. Absent if it has not been viewed yet.
format: date-time
lastViewedByUserId:
type: string
description: >-
The ID of the user who last viewed the report. Absent if it has not
been viewed yet.
name:
type: string
description: The name of the report.
ownerUserId:
type: string
description: >-
The ID of the user who owns the report. Absent if the report is
currently unowned.
permissions:
$ref: '#/components/schemas/PublicReportPermissions'
tags:
type: array
description: >-
Array of objects representing the tags that the report is tagged
with.
Only returned when requested by including the `tags` field in the
`properties` query parameter.
items:
$ref: '#/components/schemas/PublicTag'
updatedAt:
type: string
description: >-
The date and time when the report was last updated, in ISO 8601
format.
format: date-time
updatedByUserId:
type: string
description: The ID of the user who last updated the report. May be absent.
Error:
required:
- category
- correlationId
- message
type: object
properties:
category:
type: string
description: The error category, represented as a string.
context:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
An object providing context about the error condition, with
additional properties as arrays of strings.
example: >-
{invalidPropertyName=[propertyValue], missingScopes=[scope1,
scope2]}
correlationId:
type: string
description: >-
A unique identifier for the request, used for tracking and support
purposes. It is a string formatted as a UUID.
format: uuid
example: aeb5f871-7f07-4993-9211-075dc63e7cbf
errors:
type: array
description: >-
An array containing further information about the error, with each
item being an ErrorDetail object.
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. It is an object
with string properties.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate. It is a string.
example: An error occurred
subCategory:
type: string
description: >-
A specific category providing more detailed information about the
error. It is a string.
description: >-
Represents an error response returned by the API when an operation
fails. This component is used in various endpoints to provide detailed
information about the error encountered.
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: A string token representing the cursor for the next page of results.
link:
type: string
description: A string URL that links to the next page of results.
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: >-
A string token representing the cursor for the previous page of
results.
link:
type: string
description: A string URL that links to the previous page of results.
description: >-
specifies the paging information needed to retrieve the previous set of
results in a paginated API response
PublicReportPermissions:
required:
- permissionType
type: object
properties:
permissionType:
type: string
description: >-
The type of permission to apply to the report. Valid values are:
- PRIVATE: The report is only accessible to its owner and
administrators.
- EVERYONE_VIEW: The report is viewable by everyone.
- EVERYONE_EDIT: The report is viewable and editable by everyone.
- SPECIFIC: In addition to the owner, specific users and/or teams
are granted VIEW or EDIT permissions. The `specificPermissions`
field must also be present.
enum:
- EVERYONE_EDIT
- EVERYONE_VIEW
- PRIVATE
- SPECIFIC
specificPermissions:
$ref: '#/components/schemas/PublicSpecificPermissionConfig'
PublicTag:
required:
- id
- name
type: object
properties:
createdAt:
type: string
description: >-
The date and time when the tag was created, in ISO 8601 format. May
be absent.
format: date-time
createdByUserId:
type: string
description: The ID of the user who created the tag. May be absent.
id:
type: string
description: The ID for the tag.
name:
type: string
description: The name of the tag.
updatedAt:
type: string
description: >-
The date and time when the tag was last updated, in ISO 8601 format.
May be absent.
format: date-time
updatedByUserId:
type: string
description: The ID of the user who last updated the tag. May be absent.
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, represented as an object with
additional properties that are arrays of strings.
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.
description: >-
Represents detailed information about an error that occurred in the API.
This component is used to provide additional context and specifics about
errors, typically as part of an error response.
PublicSpecificPermissionConfig:
required:
- permissionType
type: object
properties:
grants:
type: array
description: >-
An array of grants detailing the users and/or teams to grant the
specific permission to. At least one grantee must be specified.
items:
$ref: '#/components/schemas/PublicPermissionGrant'
permissionType:
type: string
description: The type of permission granted, either `VIEW` or `EDIT`.
enum:
- EDIT
- VIEW
PublicPermissionGrant:
required:
- grantType
- granteeId
type: object
properties:
grantType:
type: string
description: The type of entity to grant permissions to, either `USER` or `TEAM`.
enum:
- TEAM
- USER
granteeId:
type: string
description: The ID of the user or team to grant permissions to.
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:
crm.hubsql.execute: ''
reporting.full.admin: ''
reporting.full.edit: ''
reporting.full.read: ''
reporting.full.write: ''
````
{product.name} -
{product.level}
)}