For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
LoginStart trialGet a demo
  • Welcome
    • Getting Started
    • Create an API Key
    • Pagination
    • Rate Limiting
    • No-Code Integrations
  • Webhooks
  • OAuth2
  • API Reference
      • POSTCreate post <Badge intent="info" minimal outlined>OAuth Scope: posts:write</Badge>
      • PATCHUpdate post <Badge intent="info" minimal outlined>OAuth Scope: posts:write</Badge>
      • GETList posts <Badge intent="info" minimal outlined>OAuth Scope: posts:read</Badge>
      • GETGet aggregate stats <Badge intent="info" minimal outlined>OAuth Scope: posts:read</Badge>
      • GETGet post <Badge intent="info" minimal outlined>OAuth Scope: posts:read</Badge>
      • DELDelete post <Badge intent="info" minimal outlined>OAuth Scope: posts:write</Badge>
LogoLogo
LoginStart trialGet a demo
API ReferencePosts

List posts OAuth Scope: posts:read

GET
https://api.beehiiv.com/v2/publications/:publicationId/posts
GET
/v2/publications/:publicationId/posts
$curl https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts \
>     -H "Authorization: Bearer <token>"
1{
2  "data": [
3    {
4      "id": "post_00000000-0000-0000-0000-000000000000",
5      "subtitle": "New post subtitle",
6      "title": "New Post Title",
7      "authors": [
8        "Clark Kent"
9      ],
10      "created": 1666800076,
11      "status": "draft",
12      "split_tested": true,
13      "subject_line": "Check this out",
14      "preview_text": "More news on the horizon",
15      "slug": "slug",
16      "thumbnail_url": "thumbnail_url",
17      "web_url": "web_url",
18      "audience": "free",
19      "platform": "web",
20      "content_tags": [
21        "content_tags"
22      ],
23      "hidden_from_feed": true,
24      "enforce_gated_content": false,
25      "email_capture_popup": false,
26      "publish_date": 1666800076,
27      "displayed_date": 1666800076,
28      "meta_default_description": "A post with great content",
29      "meta_default_title": "My great post",
30      "newsletter_list_id": "nl_list_00000000-0000-0000-0000-000000000000",
31      "content": {
32        "free": {
33          "web": "<HTML><body><h1>New Post</h1></body></HTML>",
34          "email": "<HTML><body><h1>New Post</h1></body></HTML>",
35          "rss": "<HTML><body><h1>New Post</h1></body></HTML>"
36        },
37        "premium": {
38          "web": "<HTML><body><h1>New Post</h1></body></HTML>",
39          "email": "<HTML><body><h1>New Post</h1></body></HTML>"
40        }
41      },
42      "stats": {
43        "email": {
44          "recipients": 100,
45          "delivered": 100,
46          "opens": 50,
47          "unique_opens": 45,
48          "open_rate": 45,
49          "clicks": 10,
50          "unique_clicks": 8,
51          "verified_clicks": 9,
52          "unique_verified_clicks": 7,
53          "click_rate": 8,
54          "unsubscribes": 1,
55          "spam_reports": 1
56        },
57        "web": {
58          "views": 200,
59          "clicks": 40
60        },
61        "clicks": [
62          {
63            "url": "https://www.google.com",
64            "base_url": "https://www.google.com",
65            "email": {
66              "clicks": 10,
67              "unique_clicks": 8,
68              "verified_clicks": 9,
69              "unique_verified_clicks": 7,
70              "click_through_rate": 80
71            },
72            "web": {
73              "clicks": 40,
74              "unique_clicks": 40,
75              "click_through_rate": 20
76            },
77            "total_clicks": 50,
78            "total_unique_clicks": 48,
79            "total_click_through_rate": 40
80          }
81        ]
82      }
83    }
84  ],
85  "limit": 1,
86  "page": 1,
87  "total_results": 1,
88  "total_pages": 1
89}
Retrieve all posts belonging to a specific publication
Was this page helpful?
Previous

Get aggregate stats OAuth Scope: posts:read

Next
Built with

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"
The prefixed ID of the publication object

Query parameters

expandlist of enumsOptional
Optionally expand the results by adding additional information. <br>`stats` - Adds statistics about the post(s). <br>`free_web_content` - Adds the web HTML rendered to a free reader. <br>`free_email_content` - Adds the email HTML rendered to a free reader. <br>`free_rss_content` - Adds the RSS feed HTML. <br>`premium_web_content` - Adds the web HTML rendered to a premium reader. <br>`premium_email_content` - Adds the email HTML rendered to a premium reader.
audienceenumOptionalDefaults to all
Optionally filter the results by audience
Allowed values:
platformenumOptionalDefaults to all

Optionally filter the results by platform.
web - Posts only published to web.
email - Posts only published to email.
both - Posts published to email and web.
all - Does not restrict results by platform.

Allowed values:
statusenumOptionalDefaults to all

Optionally filter the results by the status of the post.
draft - not been scheduled.
confirmed - The post will be active after the scheduled_at.
archived - The post is no longer active.
all - Does not restrict results by status.

Allowed values:
content_tags[]list of stringsOptional

Optionally filter posts by content_tags. Adding a content tag will return any post with that content tag associated to it.

Example: Filtering for content_tags: ["sales","closing"] will return results of posts that have either sales or closing content_tags.

slugs[]list of stringsOptional

Optionally filter posts by their slugs. Adding a slug will return any post with that exact slug associated to it.

Example: Filtering for slugs: ["my-first-post","another-post"] will return results of posts that have either my-first-post or another-post as their slug.

authors[]list of stringsOptional

Optionally filter posts by their authors. Adding an author name will return any post with that author associated to it (case-insensitive).

Example: Filtering for authors: ["John Doe","Jane Smith"] will return results of posts that have either John Doe or Jane Smith as authors.

premium_tierslist of stringsOptional

Optionally filter posts by audience based on premium tiers.
This takes in an array of Display Names of the premium tiers.
It will also scope any expanded content output to the specified premium tiers.
Note: This is case insensitive.

limitintegerOptional
A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.
pageintegerOptional

Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10).
If not specified, results 1-10 from page 1 will be returned.

order_byenumOptionalDefaults to created
The field that the results are sorted by. Defaults to created<br> `created` - The time in which the post was first created.<br> `publish_date` - The time the post was set to be published.<br> `displayed_date` - The time displayed in place of the `publish_date`. If no `displayed_date` was set, it will default to the `publish_date`
Allowed values:
directionenumOptionalDefaults to asc

The direction that the results are sorted in. Defaults to asc
asc - Ascending, sorts from smallest to largest.
desc - Descending, sorts from largest to smallest.

Allowed values:
hidden_from_feedenumOptionalDefaults to all

Optionally filter the results by the hidden_from_feed attribute of the post.
all - Does not restrict results by hidden_from_feed.
true - Only return posts hidden from the feed.
false - Only return posts that are visible on the feed.

Allowed values:

Response

OK
datalist of objects
limitinteger
The limit placed on the results. If no limit was specified in the request,this defaults to 10.
pageinteger>=0Defaults to 1
The page number the results are from. If no page was specified in the request, this defaults to page 1.
total_resultsinteger
The total number of results from all pages.
total_pagesinteger
The total number of pages.

Errors

400
Bad Request Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error

Optionally expand the results by adding additional information.
stats - Adds statistics about the post(s).
free_web_content - Adds the web HTML rendered to a free reader.
free_email_content - Adds the email HTML rendered to a free reader.
free_rss_content - Adds the RSS feed HTML.
premium_web_content - Adds the web HTML rendered to a premium reader.
premium_email_content - Adds the email HTML rendered to a premium reader.

The field that the results are sorted by. Defaults to created
created - The time in which the post was first created.
publish_date - The time the post was set to be published.
displayed_date - The time displayed in place of the publish_date. If no displayed_date was set, it will default to the publish_date