There's a new version of the HubSpot API

Check out the new API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

List events

Last updated May 22, 2023

GET /calendar/v1/events

Please note: all calendar API endpoints are being sunset and are no longer supported. These APIs will no longer function, and data from the marketing calendar will no longer be available via API. These APIs will be removed on August 31, 2023.

Method Details

HTTP Methods:

GET

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

Get an aggregation for all calendar event types. Supports filtering.
Required Parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
Start Date startDate=X - Used in the request URL The beginning value of the query range, in UTC, in milliseconds
End Date endDate=X - Used in the request URL The end value of the query range, in UTC, in milliseconds

Optional query string filters & options

Parameter name Description
limit The maximum number of items to return PER SOURCE (Content, Social, Tasks). Defaults to 100.
type The events to include, values include "CONTENT" (blog posts, email, landing pages), "SOCIAL", and "PUBLISHING_TASK" and "PUBLISHING_TASK". Multiple can be specified. Defaults to showing all types if not included.
contentCategory The category of content to filter by, values include "blog-post", "email", "recurring-email" and "landing-page". Multiple can be specified. Defaults to not filtering, showing all types
campaignGuid Show tasks by campaign guid. Multiple can be specified.
includeNoCampaigns Show tasks without a campaign specified (true, false). Defaults to false.

JSON Fields returned in the response

Field name Type Description
id string The unique id of the task
portalId string The hub id
eventDate long If task, When the task is set to be due, otherwise when the event is/ was scheduled for; in milliseconds since the epoch
eventType string Type of calendar event; for tasks this is PUBLISHING_TASK, for COS Items, this is CONTENT, for social media events, this is SOCIAL
category string type of event; if the event type is PUBLISHING_TASK, it is one of BLOG_POST, EMAIL, LANDING_PAGE, CUSTOM; if event type is SOCIAL, it is one of twitter, facebook, linkedin, googlepluspages; if event type is CONTENT, it is one of email, recurring-email, blog-post, landing-page, legacy-page, site-page
categoryId integer for event type of PUBLISHING_TASK, a numeric value corresponding to the type of task; one of 3 (BLOG_POST), 2 (EMAIL), 1 (LANDING_PAGE), 0 (CUSTOM); for event type of SOCIAL, this is 0; if event type is CONTENT, it is one of 2 (email, recurring-email), 3 (blog-post), 1 (landing-page), 5 (legacy-page), 4 (site-page)
contentId long id value of the COS content object associated with the event, null for social or if nothing associated
state string for type publishing task, value of TODO or DONE, for others, a value of SCHEDULED, PUBLISHED, PUBLISHED_OR_SCHEDULED
campaignGuid string value of campaign GUID associated with Task
contentGroupId long The ID of the content group (aka blog) that the associated Blog Post belongs to, if any. Otherwise null. Only populated for single task GETs and for Blog Post Tasks.
topicIds list of longs The list of ids of topics associated with the associated Blog Post, if any. Otherwise null. Only populated for single task GETs and for Blog Post Tasks.
name string Name of Event
description string description of Event
url string public url of content item
ownerId long TASK - HubSpot id of the user that the task is assigned to
createdBy long HubSpot id of the user that the event was created by
previewKey string preview key of content object; used for showing previews of unpublished items.
socialUserName string SOCIAL - social media user name associated with event
socialDisplayName string SOCIAL - social media full name associate with event
avatarUrl string SOCIAL - url of image associated with social media event
recurring boolean is the event recurring? (true, false)

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example GET URL: https://api.hubapi.com/calendar/v1/events?startDate=1414281600000&endDate=1417910400000&limit=2 Example response: [ { "id": "2087009576", "eventType": "CONTENT", "eventDate": 1415975962000, "category": "email", "categoryId": 2, "contentId": 2087009576, "state": "PUBLISHED", "campaignGuid": "", "portalId": 62515, "name": "Z 20141114-0937", "description": "", "url": "http://62515.hs-sites.com/-temporary-slug-5966d673-e0f4-4600-9417-9b173bf0d7de", "ownerId": null, "createdBy": 215482, "createContent": true, "previewKey": "jwVDH6Z9", "templatePath": null, "socialUsername": null, "socialDisplayName": null, "avatarUrl": null, "isRecurring": false, "topicIds": null, "contentGroupId": null, "groupId": null, "groupOrder": null, "remoteId": 0 }, { "id": "9213914", "eventType": "SOCIAL", "eventDate": 1414620448396, "category": "twitter", "categoryId": 0, "contentId": null, "state": "PUBLISHED", "campaignGuid": null, "portalId": 62515, "name": null, "description": "Post With Image 20141028-180746", "url": "https://twitter.com/Z123QA/status/527582515264258048", "ownerId": null, "createdBy": 0, "createContent": true, "previewKey": null, "templatePath": null, "socialUsername": "Z123QA", "socialDisplayName": "Z123 QA", "avatarUrl": "https://abs.twimg.com/sticky/default_profile_images/default_profile_2_reasonably_small.png", "isRecurring": false, "topicIds": null, "contentGroupId": null, "groupId": null, "groupOrder": null, "remoteId": 0 } ]