> ## 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: edd5449e-a2d7-4b0d-ba1d-4cbbd04a3379
---
# Batch retrieve campaigns
> Retrieve a batch of campaigns using specified parameters. This endpoint allows you to filter campaigns by date range and select specific properties to include in the response. It is useful for obtaining detailed information about multiple campaigns at once.
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-09-beta/marketing-campaigns-public-api-v2026-09-beta.json POST /marketing/campaigns/2026-09-beta/batch/read
openapi: 3.0.1
info:
title: Marketing Campaigns Public Api
description: Basepom for all HubSpot Projects
version: 2026-09-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: Advanced
- name: Assets
- name: Basic
- name: Batch
- name: Budget
- name: Reports
- name: Spend
paths:
/marketing/campaigns/2026-09-beta/batch/read:
post:
tags:
- Batch
summary: Batch retrieve campaigns
description: >-
Retrieve a batch of campaigns using specified parameters. This endpoint
allows you to filter campaigns by date range and select specific
properties to include in the response. It is useful for obtaining
detailed information about multiple campaigns at once.
operationId: post-/marketing/campaigns/2026-09-beta/batch/read
parameters:
- name: endDate
in: query
description: The end date for filtering campaigns, formatted as a string.
required: false
style: form
explode: true
schema:
type: string
- name: properties
in: query
description: A comma-separated list of property names to include in the response.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: startDate
in: query
description: The start date for filtering campaigns, formatted as a string.
required: false
style: form
explode: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchInputPublicCampaignReadInput'
required: true
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/BatchResponsePublicCampaignWithAssets'
'207':
description: multiple statuses
content:
application/json:
schema:
$ref: >-
#/components/schemas/BatchResponsePublicCampaignWithAssetsWithErrors
default:
$ref: '#/components/responses/Error'
description: ''
security:
- oauth2:
- marketing.campaigns.read
components:
schemas:
BatchInputPublicCampaignReadInput:
required:
- inputs
type: object
properties:
inputs:
type: array
description: >-
An array of PublicCampaignReadInput objects, each containing the ID
of a campaign to be read. This property is required.
items:
$ref: '#/components/schemas/PublicCampaignReadInput'
BatchResponsePublicCampaignWithAssets:
required:
- completedAt
- results
- startedAt
- status
type: object
properties:
completedAt:
type: string
description: >-
The date and time when the batch operation was completed, in ISO
8601 format.
format: date-time
links:
type: object
additionalProperties:
type: string
description: >-
A map of link names to associated URIs, providing additional
resources or documentation related to the batch operation.
requestedAt:
type: string
description: >-
The date and time when the batch operation was requested, in ISO
8601 format.
format: date-time
results:
type: array
description: >-
An array of PublicCampaignWithAssets objects, representing the
campaigns involved in the batch operation.
items:
$ref: '#/components/schemas/PublicCampaignWithAssets'
startedAt:
type: string
description: >-
The date and time when the batch operation started, in ISO 8601
format.
format: date-time
status:
type: string
description: >-
The current status of the batch operation. Valid values include
'PENDING', 'PROCESSING', 'CANCELED', and 'COMPLETE'.
enum:
- CANCELED
- COMPLETE
- PENDING
- PROCESSING
BatchResponsePublicCampaignWithAssetsWithErrors:
required:
- completedAt
- results
- startedAt
- status
type: object
properties:
completedAt:
type: string
description: >-
The date and time when the batch operation was completed, in ISO
8601 format.
format: date-time
errors:
type: array
description: >-
An array of errors that occurred during the batch operation, each
described by a standard error object.
items:
$ref: '#/components/schemas/StandardError'
links:
type: object
additionalProperties:
type: string
description: >-
A map of link names to associated URIs that provide additional
information about the batch operation.
numErrors:
type: integer
description: The number of errors that occurred during the batch operation.
format: int32
requestedAt:
type: string
description: >-
The date and time when the batch operation was requested, in ISO
8601 format.
format: date-time
results:
type: array
description: >-
An array of campaigns with their associated assets that were
processed in the batch operation.
items:
$ref: '#/components/schemas/PublicCampaignWithAssets'
startedAt:
type: string
description: >-
The date and time when the batch operation started, in ISO 8601
format.
format: date-time
status:
type: string
description: >-
The current status of the batch operation. Valid values include
'PENDING', 'PROCESSING', 'CANCELED', and 'COMPLETE'.
enum:
- CANCELED
- COMPLETE
- PENDING
- PROCESSING
PublicCampaignReadInput:
required:
- id
type: object
properties:
id:
type: string
description: >-
The unique identifier for the campaign. It is a string and is
required to retrieve the campaign details.
PublicCampaignWithAssets:
required:
- assets
- businessUnits
- createdAt
- id
- properties
- updatedAt
type: object
properties:
assets:
type: object
additionalProperties:
$ref: '#/components/schemas/CollectionResponsePublicCampaignAsset'
description: >-
A map of asset types to their respective collections of campaign
assets, represented by CollectionResponsePublicCampaignAsset
objects.
businessUnits:
type: array
description: >-
An array of business units associated with the campaign, each
represented by a PublicBusinessUnit object.
items:
$ref: '#/components/schemas/PublicBusinessUnit'
createdAt:
type: string
description: The date and time when the campaign was created, in ISO 8601 format.
format: date-time
id:
type: string
description: The unique identifier for the campaign, represented as a string.
properties:
type: object
additionalProperties:
type: string
description: >-
A map of custom property names to their values, where each value is
a string.
updatedAt:
type: string
description: >-
The date and time when the campaign was last updated, in ISO 8601
format.
format: date-time
StandardError:
required:
- category
- context
- errors
- links
- message
- status
type: object
properties:
category:
type: string
description: A string categorizing the type of error.
context:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
An object containing additional context about the error, with keys
as context names and values as arrays of strings.
errors:
type: array
description: >-
An array of ErrorDetail objects providing further information about
the error.
items:
$ref: '#/components/schemas/ErrorDetail'
id:
type: string
description: A string representing a unique identifier for the error.
links:
type: object
additionalProperties:
type: string
description: >-
An object mapping link names to associated URIs that contain
documentation or remediation steps related to the error.
message:
type: string
description: A string containing a human-readable message describing the error.
status:
type: string
description: A string indicating the status of the error.
subCategory:
type: object
properties: {}
description: An object providing more specific categorization of the error.
description: Ye olde error
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, where each
key is a string and each value is an array of strings.
example: >-
{invalidPropertyName=[propertyValue], missingScopes=[scope1,
scope2]}
correlationId:
type: string
description: >-
A unique identifier for the request, formatted as a UUID. This
should be included with any error reports or support tickets.
format: uuid
example: aeb5f871-7f07-4993-9211-075dc63e7cbf
errors:
type: array
description: >-
An array providing 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, represented as an
object with string values.
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 that contains more specific detail about the
error, represented as a string.
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
CollectionResponsePublicCampaignAsset:
required:
- results
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
results:
type: array
description: >-
An array of PublicCampaignAsset objects, each representing an
individual campaign asset.
items:
$ref: '#/components/schemas/PublicCampaignAsset'
PublicBusinessUnit:
required:
- id
type: object
properties:
id:
type: integer
description: >-
The unique identifier for the business unit, represented as a 64-bit
integer.
format: int64
ErrorDetail:
required:
- message
type: object
properties:
code:
type: string
description: The status code associated with the error detail. This is a string.
context:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
Context about the error condition, provided as an object where each
key is a context name and the value is an array of strings providing
additional information.
example: '{missingScopes=[scope1, scope2]}'
in:
type: string
description: >-
The name of the field or parameter in which the error was found.
This is a string.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate. This is a string.
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error. This is a string.
Paging:
type: object
properties:
next:
$ref: '#/components/schemas/NextPage'
prev:
$ref: '#/components/schemas/PreviousPage'
PublicCampaignAsset:
required:
- id
type: object
properties:
id:
type: string
description: >-
The unique identifier for the campaign asset, represented as a
string.
metrics:
type: object
additionalProperties:
type: number
description: >-
A collection of performance metrics for the campaign asset,
represented as a map where each key is a metric name and each value
is a number.
name:
type: string
description: The name of the campaign asset, represented as a string.
NextPage:
required:
- after
type: object
properties:
after:
type: string
description: >-
A string token that serves as the paging cursor, indicating the
position after the last successfully read resource.
link:
type: string
description: A string URL that provides a link 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 used to identify the position before the current page
in the paginated results.
link:
type: string
description: A URL string that provides a link to the previous page of results.
description: >-
specifies the paging information needed to retrieve the previous set of
results in a paginated API response
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:
marketing.campaigns.read: ''
marketing.campaigns.revenue.read: ''
marketing.campaigns.write: ''
````
{product.name} -
{product.level}
)}