List posts | beehiiv | Developer Documentation

Retrieve all posts belonging to a specific publication

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"

The prefixed ID of the publication object

Headers

AuthorizationstringRequired

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

Query parameters

expandlist of enumsOptional

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.

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.

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
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

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

datalist of objects

limitinteger

The limit placed on the results. If no limit was specified in the request,this defaults to 10.

pageinteger>=0

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.

1	import requests
2
3	url = "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts"
4
5	headers = {"Authorization": "Bearer <token>"}
6
7	response = requests.get(url, headers=headers)
8
9	print(response.json())

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	"publish_date": 1666800076,
25	"displayed_date": 1666800076,
26	"meta_default_description": "A post with great content",
27	"meta_default_title": "My great post",
28	"content": {
29	"free": {
30	"web": "<HTML><body><h1>New Post</h1></body></HTML>",
31	"email": "<HTML><body><h1>New Post</h1></body></HTML>",
32	"rss": "<HTML><body><h1>New Post</h1></body></HTML>"
33	},
34	"premium": {
35	"web": "<HTML><body><h1>New Post</h1></body></HTML>",
36	"email": "<HTML><body><h1>New Post</h1></body></HTML>"
37	}
38	},
39	"stats": {
40	"email": {
41	"recipients": 100,
42	"delivered": 100,
43	"opens": 50,
44	"unique_opens": 45,
45	"open_rate": 45,
46	"clicks": 10,
47	"unique_clicks": 8,
48	"click_rate": 8,
49	"unsubscribes": 1,
50	"spam_reports": 1
51	},
52	"web": {
53	"views": 200,
54	"clicks": 40
55	},
56	"clicks": [
57	{
58	"url": "https://www.google.com",
59	"email": {
60	"clicks": 10,
61	"unique_clicks": 8,
62	"click_through_rate": 80
63	},
64	"web": {
65	"clicks": 40,
66	"unique_clicks": 40,
67	"click_through_rate": 20
68	},
69	"total_clicks": 50,
70	"total_unique_clicks": 48,
71	"total_click_through_rate": 40
72	}
73	]
74	}
75	}
76	],
77	"limit": 1,
78	"page": 1,
79	"total_results": 1,
80	"total_pages": 1
81	}

Path parameters

Headers

Query parameters

Response

Errors