List posts
list_postsRead-onlyIdempotent
Retrieve posts from a Beehiiv publication, with filters for status, author, audience, platform, and tags. Supports pagination and expansion for detailed data.
Instructions
List posts. Reads account data. OAuth integrations require posts:read.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 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. | |
| limit | No | A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. | |
| slugs | No | 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. | |
| expand | No | 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. | |
| status | No | 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. | all |
| account | No | Named private account from BEEHIIV_ACCOUNTS. Defaults to BEEHIIV_DEFAULT_ACCOUNT or the first configured account. | |
| authors | No | 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. | |
| audience | No | Optionally filter the results by audience | all |
| order_by | No | 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` | created |
| platform | No | 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. | all |
| direction | No | 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. | asc |
| content_tags | No | 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. | |
| premium_tiers | No | 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. | |
| publication_id | Yes | The prefixed ID of the publication object | |
| hidden_from_feed | No | 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. | all |