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

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

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

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

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

direction"asc" or "desc"OptionalDefaults 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: ascdesc

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

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	{
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	"clicks": 10,
46	"unique_clicks": 8,
47	"unsubscribes": 1,
48	"spam_reports": 1
49	},
50	"web": {
51	"views": 200,
52	"clicks": 40
53	},
54	"clicks": [
55	{
56	"total_clicks": 10,
57	"total_unique_clicks": 8,
58	"total_click_through_rate": 30
59	}
60	]
61	}
62	}
63	],
64	"limit": 1,
65	"page": 1,
66	"total_results": 1,
67	"total_pages": 1
68	}

1	curl https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts \
2	-H "Authorization: Bearer <token>"

Path parameters

Query parameters

Response

Errors