> ## 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: 09d11f33-de1f-4a86-ad09-0615a9c2260b
---
# Get campaigns
> This endpoint reads a batch of campaigns based on the provided input data and returns the campaigns along with their associated assets.
The maximum number of items in a batch request is 50.
The campaigns in the response are not guaranteed to be in the same order as they were provided in the request.
If duplicate campaign IDs are provided in the request, duplicates will be ignored. The response will include only unique IDs and will be returned without duplicates.
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-campaigns-public-api-v2026-03.json POST /marketing/campaigns/2026-03/batch/read
openapi: 3.0.1
info:
title: Marketing Campaigns Public Api
description: Basepom for all HubSpot Projects
version: 2026-03
x-hubspot-product-tier-requirements:
marketing: PROFESSIONAL
sales: FREE
service: FREE
cms: FREE
commerce: FREE
crmHub: FREE
dataHub: FREE
servers:
- url: https://api.hubapi.com
security: []
tags:
- name: Assets
- name: Basic
- name: Batch
- name: Budget
- name: Metrics
- name: Spend
paths:
/marketing/campaigns/2026-03/batch/read:
post:
tags:
- Batch
summary: Read a batch of campaigns
description: >
This endpoint reads a batch of campaigns based on the provided input
data and returns the campaigns along with their associated assets.
The maximum number of items in a batch request is 50.
The campaigns in the response are not guaranteed to be in the same order
as they were provided in the request.
If duplicate campaign IDs are provided in the request, duplicates will
be ignored. The response will include only unique IDs and will be
returned without duplicates.
operationId: post-/marketing/campaigns/2026-03/batch/read
parameters:
- name: endDate
in: query
description: >-
End date to fetch asset metrics, formatted as YYYY-MM-DD. This date
is used to fetch the metrics associated with the assets for a
specified period. If not provided, no asset metrics will be
fetched.
Example: 2024-01-27
required: false
style: form
explode: true
schema:
type: string
- name: properties
in: query
description: >-
A comma-separated list of the properties to be returned in the
response. If any of the specified properties has empty value on the
requested object(s), they will be ignored and not returned in
response. If this parameter is empty, the response will include an
empty properties map.
Example: hs_name, hs_campaign_status, hs_notes
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: startDate
in: query
description: >-
Start date to fetch asset metrics, formatted as YYYY-MM-DD. This
date is used to fetch the metrics associated with the assets for a
specified period. If not provided, no asset metrics will be
fetched.
Example: 2023-01-20
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 timestamp when the batch request processing was completed.
format: date-time
links:
type: object
additionalProperties:
type: string
description: A collection of URLs linking to related resources or documentation.
requestedAt:
type: string
description: The timestamp when the batch request was initially made.
format: date-time
results:
type: array
description: >-
An array of results from the batch operation, each representing a
public campaign with assets.
items:
$ref: '#/components/schemas/PublicCampaignWithAssets'
startedAt:
type: string
description: The timestamp when the processing of the batch request began.
format: date-time
status:
type: string
description: >-
The current processing status of the batch operation, with possible
values: CANCELED, COMPLETE, PENDING, PROCESSING.
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.
format: date-time
errors:
type: array
description: >-
The list of errors for individual campaign reads that failed within
the batch (e.g., campaign not found, permission denied). Only
included when non-empty.
items:
$ref: '#/components/schemas/StandardError'
links:
type: object
additionalProperties:
type: string
description: A collection of links related to 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.
format: date-time
results:
type: array
description: >-
The list of successfully retrieved campaigns with their associated
assets.
items:
$ref: '#/components/schemas/PublicCampaignWithAssets'
startedAt:
type: string
description: The date and time when the batch operation started.
format: date-time
status:
type: string
description: >-
The current status of the batch operation, which can be CANCELED,
COMPLETE, PENDING, or PROCESSING.
enum:
- CANCELED
- COMPLETE
- PENDING
- PROCESSING
PublicCampaignReadInput:
required:
- id
type: object
properties:
id:
type: string
description: The unique identifier for a campaign.
PublicCampaignWithAssets:
required:
- assets
- businessUnits
- createdAt
- id
- properties
- updatedAt
type: object
properties:
assets:
type: object
additionalProperties:
$ref: '#/components/schemas/CollectionResponsePublicCampaignAsset'
description: >-
Contains the assets associated with the campaign, each represented
as a collection of campaign assets.
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, formatted as a
date-time string.
format: date-time
id:
type: string
description: The unique identifier for the campaign.
properties:
type: object
additionalProperties:
type: string
description: >-
A map of key-value pairs representing the properties of the
campaign.
updatedAt:
type: string
description: >-
The date and time when the campaign was last updated, formatted as a
date-time string.
format: date-time
StandardError:
required:
- category
- context
- errors
- links
- message
- status
type: object
properties:
category:
type: string
description: A string that categorizes 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
each error encountered.
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 for 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 that provides more specific details about the error
category.
description: Ye olde error
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
CollectionResponsePublicCampaignAsset:
required:
- results
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
results:
type: array
description: >-
An array of public campaign assets. Each item in the array is an
object representing a 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 an
integer.
format: int64
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
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.
metrics:
type: object
additionalProperties:
type: number
description: >-
A collection of metrics associated with the campaign asset,
represented as key-value pairs.
name:
type: string
description: The name of the campaign asset.
NextPage:
required:
- after
type: object
properties:
after:
type: string
description: >-
A string token used as a cursor to retrieve the next page of
results.
link:
type: string
description: A string URL that provides the 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 that indicates the position in the list before the
current page of results.
link:
type: string
description: A string containing the URL 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.full.read: ''
marketing.campaigns.revenue.read: ''
marketing.campaigns.write: ''
````
{product.name} -
{product.level}
)}