There's a new version of the HubSpot API

Check out the new API
View Beta Docs

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

List blog posts

Last updated May 15, 2023

GET /content/api/v2/blog-posts

Method Details

HTTP Methods:

GET

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

Required Scope:

content

Get the posts from your HubSpot blogs. Supports paging and filtering. This method would be useful for an integration that examined blog posts and used an external service to suggest edits.

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.

Optional query string filters & options

If a parameter supports a filter type of 'gt', that means you can append a double underscore to the parameter name to find all items greater than the specified value. For example, the following query will find all blog posts updated after 5/1/2015: https://api.hubapi.com/content/api/v2/blog-posts?updated__gt=1430452800000&content_group_id=351076

Parameter name Description
limit The number of items to return. Defaults to 20. Cannot exceed 300.
offset The offset set to start returning rows from. Defaults to 0.
archived_at Returns the posts that match a particular deleted time value. Supports exact, gt, gte, lt, lte lookups.
archivedInDashboard Returns the posts that match the boolean lookup
(e.g. archived=false returns all posts currently not archived).
blog_author_id Returns the posts that match a particular blog author ID value.
campaign Returns the posts that match the campaign guid. The campaign guid can be found in the campaign dashboard URL
content_group_id Returns the posts that match the blog guid. The blog guid can be found using the Blog API
created Returns the posts that match a particular created time value. Supports exact, range, gt, gte, lt, lte lookups.
name Returns the posts that match the name value. Supports exact, icontains, ne lookups.
slug Returns the posts that match a particular slug value.
updated Returns the posts that match a particular updated time. Supports exact, range, gt, gte, lt, lte lookups.
state DRAFT, PUBLISHED, or SCHEDULED.
order_by Return the posts ordered by a particular field value. Blog posts can currently only be sorted by publish_date. Use a negative value to sort in descending order (e.g. order_by=-publish_date).

JSON Fields returned in the response

Parameter name Type Description
archived_at long When the post was deleted, in milliseconds since the epoch. Zero if the blog post was never deleted. Use a DELETE request to delete the post, do not set this directly.
archivedInDashboard bool If True, the post will not show up in your dashboard, although the post will still be live
blog_author_id long The integer id of the blog author, look up via the blog authors end point /content/api/v2/blog-authors
campaign string The guid of the marketing campaign this post is associated with
campaign_name string The name of the marketing campaign this post is associated with
content_group_id long The id of the blog that this post belongs to. Get the id by looking at the blog API endpoint /content/api/v2/blogs
created long When the post was first created, in milliseconds since the epoch
footer_html string Custom HTML for embed codes, javascript that should be placed before the </body> tag of the page
head_html string Custom HTML for embed codes, javascript, etc. that goes in the <head> tag of the page
is_draft string True if the post is still a draft, invisible to the public. Gets changed when the /publish-action API endpoint is called
keywords list A JSON list of keywords and their GUIDs. This list contains key value pairs of "keyword" and "keyword_guid". For example:
  • "keyword" : "sandwiches",
  • "keyword_guid" : "ee7c2292-7a2f-4f0f-81fb-ad0bd9ca4fcb"
The GUID is available from the Keywords API. This list adds keywords to the Optimization tab in HubSpot.
meta_description string A description that goes in <meta> tag on the page
name string The internal name of the blog post
post_body string The HTML of the main post body
post_summary string The summary of the blog post that will appear on the main listing page
publish_date long The date the blog post is to be published at in milliseconds since the unix epoch.
publish_immediately string Set this to true if you want to be published immediately when the schedule publish endpoint is called, and to ignore the publish_date setting
slug string The path of the URL on which the post will live. Changing this will change the URL.
topic_ids list A json list of topic ids from the topics API ( /content/api/v2/topics )
updated long When the post was last updated, in milliseconds since the epoch
url string The full URL with domain and scheme to the blog post. Will return a 404 if the post is not yet published.
widgets string A data structure containing the data for all the modules for this post. This will only be populated if the blog template has editable widgets defined.

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/content/api/v2/blog-posts

Example GET response:

 {
   "total":2,
   "objects":[
      {
         "archived":false,
         "author_user_id":100307,
         "blog_author":{
            "avatar":"",
            "bio":"",
            "body":{

            },
            "created":1377856983000,
            "deleted_at":0,
            "email":"testapi@hubspot.com",
            "facebook":"",
            "full_name":"Hub Spot",
            "google_plus":"",
            "gravatar_url":"https://app.hubspot.com/settings/avatar/bb23f3ae97b9698d130c02d2841e86a4",
            "id":284839243,
            "linkedin":"",
            "portal_id":62515,
            "slug":"hub-spot",
            "twitter":"",
            "updated":1377856983000,
            "user_id":215482,
            "username":"testapi@hubspot.com",
            "website":""
         },
         "blog_author_id":284839243,
         "campaign":null,
         "campaign_name":null,
         "cloned_from":null,
         "comment_count":0,
         "content_group_id":351076997,
         "created":1381896118000,
         "deleted_at":0,
         "featured_image":"",
         "footer_html":"",
         "freeze_date":1381896118000,
         "has_user_changes":true,
         "head_html":"",
         "html_title":"Demonstration Blog Post",
         "id":348109414,
         "is_draft":true,
         "meta_description":"This is the meta description of your first post.",
         "name":"Demonstration Blog Post",
         "performable_url":null,
         "portal_id":62515,
         "post_body":"
<p>This is an example blog post.  You can delete this blog post by going to the blog dashboard.</p>
<p>We hope you enjoy your HubSpot!</p>
",
         "post_summary":"
<p>This is an example blog post.  You can delete this blog post by going to the blog dashboard.</p>
",
         "preview_key":"AhbF8tzV",
         "processing_status":"",
         "publish_date":1381896118000,
         "publish_immediately":null,
         "published_url":"http://62515.sites.hubspot.com/blog/your-first-blog-post",
         "rss_body":"
<p>This is an example blog post.  You can delete this blog post by going to the blog dashboard.</p>
<p>We hope you enjoy your HubSpot!</p>
",
         "rss_summary":"
<p>This is an example blog post.  You can delete this blog post by going to the blog dashboard.</p>
",
         "slug":"blog/your-first-blog-post",
         "state":"PUBLISHED",
         "style_override_id":null,
         "subcategory":"normal_blog_post",
         "topic_ids":[

         ],
         "updated":1381896118000,
         "url":"http://62515.sites.hubspot.com/blog/your-first-blog-post",
         "widget_containers":{

         },
         "widgetcontainers":{

         },
         "widgets":{

         }
      },
      {
         "archived":false,
         "author_user_id":100307,
         "blog_author":{
            "avatar":"",
            "bio":"",
            "body":{

            },
            "created":1377856983000,
            "deleted_at":0,
            "email":"testapi@hubspot.com",
            "facebook":"",
            "full_name":"Hub Spot",
            "google_plus":"",
            "gravatar_url":"https://app.hubspot.com/settings/avatar/bb23f3ae97b9698d130c02d2841e86a4",
            "id":284839243,
            "linkedin":"",
            "portal_id":62515,
            "slug":"hub-spot",
            "twitter":"",
            "updated":1377856983000,
            "user_id":215482,
            "username":"testapi@hubspot.com",
            "website":""
         },
         "blog_author_id":284839243,
         "campaign":"d4c2ff5a-257d-4c4c-84a1-15e7197258fc",
         "campaign_name":"market",
         "cloned_from":null,
         "comment_count":0,
         "content_group_id":351076997,
         "created":1381896164000,
         "deleted_at":0,
         "featured_image":"",
         "footer_html":"",
         "freeze_date":1381896282000,
         "has_user_changes":true,
         "head_html":"",
         "html_title":"Demonstrating the Blog Post API",
         "id":352531735,
         "is_draft":true,
         "meta_description":"A test blog post demonstrating the API.",
         "name":"Demonstrating the Blog Post API",
         "performable_url":null,
         "portal_id":62515,
         "post_body":"<p>This blog post is meant to demonstrate the capabilities of the CMS API.</p>
<p><span>Part content system, part personalization engine. HubSpot's CMS is the first integrated website, blog and landing page system to be optimized for mobile right out-of-the-box. Fully integrated with every marketing channel, it adapts to each viewer's unique context.</span></p>
<p><span><span>HubSpot is a complete inbound marketing platform. So not only are all of the tools you use in one place, your customers get a seamless experience from email to social to web. Brilliant.</span></span></p>",
         "post_summary":"<p>This blog post is meant to demonstrate the capabilities of the CMS API.</p>
",
         "preview_key":"Bw3HHMW_",
         "processing_status":"published",
         "publish_date":1381896282000,
         "publish_immediately":true,
         "published_url":"http://62515.sites.hubspot.com/blog/demonstrating-the-blog-post-api",
         "rss_body":"<p>This blog post is meant to demonstrate the capabilities of the CMS API.</p>
<p><span>Part content system, part personalization engine. HubSpot's CMS is the first integrated website, blog and landing page system to be optimized for mobile right out-of-the-box. Fully integrated with every marketing channel, it adapts to each viewer's unique context.</span></p>
<p><span><span>HubSpot is a complete inbound marketing platform. So not only are all of the tools you use in one place, your customers get a seamless experience from email to social to web. Brilliant.</span></span></p>",
         "rss_summary":"<p>This blog post is meant to demonstrate the capabilities of the CMS API.</p>
",
         "slug":"blog/demonstrating-the-blog-post-api",
         "state":"PUBLISHED",
         "style_override_id":null,
         "subcategory":"normal_blog_post",
         "topic_ids":[
            349001328
         ],
         "updated":1381896283000,
         "url":"http://62515.sites.hubspot.com/blog/demonstrating-the-blog-post-api",
         "widget_containers":{

         },
         "widgetcontainers":{

         },
         "widgets":{
            "blog_comments":{
               "body":{

               },
               "name":"blog_comments",
               "meta":{

               },
               "type":"blog_comments",
               "id":"blog_comments",
               "css":{

               }
            }
         }
      }
   ],
   "limit":20,
   "offset":0
}