beehiiv is a newsletter platform: you publish posts by email and on the web, grow an audience of subscribers, organize them in segments and newsletter lists, run email automations, sell premium tiers and earn from the beehiiv Ad Network. This connector reads your workspace through the official beehiiv API and brings, for every publication, your subscribers, posts with their email and web stats, segments and their members, automations with their journeys and emails, daily engagement metrics, email blasts, tiers, custom fields, newsletter lists, polls, podcasts, the referral program and ad network reports.

The connector only reads data. It never creates, changes or deletes anything in beehiiv.

Configuring beehiiv as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the beehiiv option from the list of connectors. Click Next and you’ll be prompted to add your access.

1. Add account access

The beehiiv API uses an API key. To create one, open beehiiv and go to Settings > Integrations > API, click Create New API Key, give it a name (for example, Nekt) and copy the key. It is shown only once.

API Key: the key you created.
Start Date: the first day of the daily engagement metrics (the Daily engagements table). Every other table is always read in full, whatever this date.
Publication IDs (advanced, optional): the publications to sync, by ID (they start with pub_). Leave it empty to sync every publication of your workspace.

Create a key only for Nekt. beehiiv limits the number of requests per minute per key according to your plan (30 on Free, 180 on Lite, 500 on Pro, 800 on Enterprise), and a key shared with other tools makes the syncs slower. When the limit is reached, the sync pauses until it resets and then continues; no data is lost.

Once you’re done, click Next.

2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

Tip: The stream can be found more easily by typing its name.

Select the streams and click Next.

3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
Sync Type: keep the suggested type. Daily engagements is Incremental: each sync reads the last days again (they are still accumulating) and the new ones, and merges them into the table. The other tables are Full table: the beehiiv API cannot list records changed since a date, while statuses, tiers and stats keep changing on old records, so each sync reads them whole and replaces the table.

Once you are done configuring, click Next.

4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Most tables are read whole on every sync, so a daily sync is recommended; large audiences take longer, especially on the Free plan’s request limit. Optionally, you can configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here. Once you are ready, click Next to finalize the setup.

5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

For you to be able to see it on your Catalog, you need at least one successful source run.

Streams and Fields

Available streams

The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description. Every table except Publications has a publication_id column.

Stream	Slug	Sync	Description
Publications	`publications`	Full table	The publications (newsletters) the API key can access, with their current all-time stats.
Subscriptions	`subscriptions`	Full table	Every subscriber of every publication, whatever the status (active, inactive, pending…), with acquisition UTMs, custom fields, newsletter lists and engagement stats.
Posts	`posts`	Full table	Every post (draft, scheduled, sent, archived) with its all-time email and web stats. Clicks per URL are in `stats_clicks`.
Segments	`segments`	Full table	Segments of every type and status, with the stats of their latest calculation.
Segment members	`segment_members`	Full table	Which subscriptions belong to each segment, as of the segment’s last calculation. Join `subscription_id` with `subscriptions.id`.
Automations	`automations`	Full table	Automations (email workflows) with their journey counts and aggregate email stats.
Automation journeys	`automation_journeys`	Full table	Every subscriber’s journey through every automation: when it started, finished or exited.
Automation emails	`automation_emails`	Full table	The emails of every automation step (and A/B variant), with their engagement stats.
Daily engagements	`engagements`	Incremental	Opens and clicks per day for each publication, for every email sent (posts and automations).
Email blasts	`email_blasts`	Full table	One-off email blasts, active and inactive, with their stats.
Tiers	`tiers`	Full table	Premium (paid) tiers with their prices and number of active subscriptions.
Custom fields	`custom_fields`	Full table	The custom subscriber fields defined on each publication.
Newsletter lists	`newsletter_lists`	Full table	Newsletter lists (sub-newsletters subscribers opt in to).
Newsletter list subscriptions	`newsletter_list_subscriptions`	Full table	Which subscriptions joined each newsletter list, and when they joined and left.
Authors	`authors`	Full table	Authors (users and guest authors) available to the posts.
Polls	`polls`	Full table	Polls (voting and trivia) with their choices and vote counts.
Poll responses	`poll_responses`	Full table	Every subscriber response to every poll, with the post where it was collected.
Podcasts	`podcasts`	Full table	Podcasts hosted on beehiiv.
Podcast episodes	`podcast_episodes`	Full table	Episodes of every podcast.
Referral program milestones	`referral_program_milestones`	Full table	Milestones of the referral program and their rewards.
Ad network reports	`ad_network_reports`	Full table	Ad network performance and payments: one row per advertisement link per post. Only for publications in the beehiiv Ad Network.

Tables that depend on a beehiiv feature

The API key reads everything your workspace has; there is no permission to grant per table. Some tables, however, read features that beehiiv offers only on some plans or to eligible publications:

Table(s)	beehiiv feature needed
Ad network reports	beehiiv Ad Network (eligible publications only)
Tiers	Premium subscriptions (paid tiers)
Automations, Automation journeys, Automation emails	Automations
Polls, Poll responses	Polls
Podcasts, Podcast episodes	Podcasts
Referral program milestones	Referral program
Newsletter lists, Newsletter list subscriptions	Newsletter lists
Email blasts	Email blasts
All other tables	Any plan

When beehiiv refuses access to a table for any of your publications, that table is skipped in the sync (it is not updated) and the log names it and the publication; the other tables keep syncing. Deselect the table to stop the warning.

Fields by stream

Dates and times are in UTC. Fields marked String (JSON) hold a nested object or list as JSON text; use your warehouse’s JSON functions to read them. Stats are all-time totals as of the sync; use Daily engagements for opens and clicks per day.

Publications

The publications (newsletters) the API key can access, with their current all-time stats.Table: publications · Primary key: id · Sync: Full table

Field	Type	Description
`id`	String	Unique prefixed ID of the publication (pub_…).
`name`	String	Name of the publication.
`organization_name`	String	Name of the organization that owns the publication.
`referral_program_enabled`	Boolean	Whether the referral program is active for this publication.
`created`	Datetime	When the publication was created (UTC).
`stats_active_subscriptions`	Integer	Current number of active free and premium subscriptions.
`stats_active_premium_subscriptions`	Integer	Current number of active premium (paid) subscriptions.
`stats_active_free_subscriptions`	Integer	Current number of active free subscriptions.
`stats_average_open_rate`	Number	Historical average email open rate of the publication (percentage).
`stats_average_click_rate`	Number	Historical average email click-through rate of the publication (percentage).
`stats_total_sent`	Integer	Total number of emails sent by the publication.
`stats_total_unique_opened`	Integer	Total number of uniquely opened emails (first open per subscriber).
`stats_total_clicked`	Integer	Total number of links clicked from the publication’s emails.

Subscriptions

Every subscriber of every publication, whatever the status (active, inactive, pending…), with acquisition UTMs, custom fields, newsletter lists and engagement stats.Table: subscriptions · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the subscription (sub_…).
`email`	String	Email address of the subscriber.
`status`	String	Subscription status: validating, invalid, pending, active, inactive, needs_attention, paused or unset.
`created`	Datetime	When the subscription was created (UTC).
`subscription_tier`	String	Current tier of the subscription: free or premium.
`subscription_premium_tier_names`	Array of strings	Names of the premium tiers the subscription currently belongs to.
`subscription_premium_tiers`	String (JSON)	Premium tiers of the subscription, when returned by beehiiv (JSON array of objects with id, name and status).
`utm_source`	String	Acquisition source: where the subscriber came from.
`utm_medium`	String	Acquisition medium: how the subscriber got to the publication.
`utm_channel`	String	Acquisition channel (website, import, embed, api, referral, recommendation, boost, integration…).
`utm_campaign`	String	Acquisition campaign.
`utm_term`	String	Acquisition term, usually the keyword or search term.
`utm_content`	String	Acquisition content, usually used for A/B tests or ad variations.
`referring_site`	String	Website the subscriber was referred from.
`referral_code`	String	Code this subscriber shares to refer others.
`custom_fields`	String (JSON)	Custom field values of the subscription (JSON array of objects with name, kind and value).
`tags`	Array of strings	Tags applied to the subscription, when returned by beehiiv.
`newsletter_list_ids`	Array of strings	Prefixed IDs of the newsletter lists the subscription is actively subscribed to.
`stats_emails_received`	Integer	Total number of emails sent to this subscriber.
`stats_open_rate`	Number	Percentage of emails the subscriber opened.
`stats_click_through_rate`	Number	Percentage of emails in which the subscriber clicked a link.

Posts

Every post (draft, scheduled, sent, archived) with its all-time email and web stats. Clicks per URL are in stats_clicks.Table: posts · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the post (post_…).
`title`	String	Title displayed in web views.
`subtitle`	String	Subtitle displayed in web views.
`authors`	Array of strings	Names of the post’s authors.
`created`	Datetime	When the post was created (UTC).
`status`	String	Status of the post: draft, confirmed (scheduled or published) or archived.
`publish_date`	Datetime	When the post was set to be published (UTC).
`displayed_date`	Datetime	Date displayed in place of the publish date (UTC).
`split_tested`	Boolean	Whether an A/B split test was run on the email subject.
`subject_line`	String	Email subject line (the winning one when split tested).
`preview_text`	String	Email preview text.
`slug`	String	Web slug where the post can be accessed.
`thumbnail_url`	String	URL of the post thumbnail.
`web_url`	String	Full URL of the post on the web (web or both platforms only).
`preview_url`	String	URL of the post’s email preview in the beehiiv app.
`audience`	String	Web audience of the post: free, premium or both.
`platform`	String	Where the post is published: web, email or both.
`content_tags`	Array of strings	Content tags associated with the post.
`meta_default_title`	String	SEO title of the post.
`meta_default_description`	String	SEO description of the post.
`newsletter_list_id`	String	Prefixed ID of the newsletter list the post targets, if any.
`hidden_from_feed`	Boolean	Whether the post is hidden from the website feed.
`enforce_gated_content`	Boolean	Whether the post enforces gated content for non-subscribers.
`email_capture_popup`	Boolean	Whether the email capture popup is enabled for the post.
`recipients`	String (JSON)	Targeting configuration of the post: tiers and segments included or excluded, per web and email (JSON object).
`recipient_count`	Integer	Estimated (draft/scheduled) or actual (sent) number of email subscribers targeted.
`headers`	String (JSON)	Custom email headers set on the post (JSON object).
`from_address`	String	From address of the post.
`reply_to_address`	String	Reply-to address of the post.
`sender_name`	String	Sender name preset of the post.
`utm_source`	String	utm_source of the post.
`utm_medium`	String	utm_medium of the post.
`utm_campaign`	String	utm_campaign of the post.
`utm_params_enabled`	Boolean	Whether UTM parameters are appended to links in the post.
`reusable_header_block_id`	String	Prefixed ID of the reusable header block of the post’s email.
`reusable_footer_block_id`	String	Prefixed ID of the reusable footer block of the post’s email.
`stats_email_recipients`	Integer	Total number of email recipients of the post.
`stats_email_delivered`	Integer	Total number of emails of the post delivered.
`stats_email_opens`	Integer	Total number of email opens of the post.
`stats_email_unique_opens`	Integer	Number of unique email opens of the post.
`stats_email_open_rate`	Number	Percentage of emails of the post that were opened.
`stats_email_clicks`	Integer	Total number of email clicks of the post.
`stats_email_unique_clicks`	Integer	Number of unique email clicks of the post.
`stats_email_verified_clicks`	Integer	Total number of verified human email clicks of the post (passed beehiiv bot detection).
`stats_email_unique_verified_clicks`	Integer	Number of unique verified human email clicks of the post.
`stats_email_click_rate`	Number	Percentage of emails of the post that were clicked.
`stats_email_unsubscribes`	Integer	Total number of unsubscribes caused by the post.
`stats_email_spam_reports`	Integer	Number of subscribers who reported the post as spam.
`stats_web_views`	Integer	Total number of web views of the post.
`stats_web_clicks`	Integer	Total number of web clicks of the post.
`stats_upgrades`	Integer	Free-to-premium upgrades attributed to the post.
`stats_clicks`	String (JSON)	Click statistics per URL in the post, for email and web (JSON array of objects).

Segments

Segments of every type and status, with the stats of their latest calculation.Table: segments · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the segment (seg_…).
`name`	String	Name of the segment.
`type`	String	Segment type: dynamic (recalculated at intervals), static (calculated once) or manual.
`last_calculated`	Datetime	When the segment was last calculated (UTC).
`total_results`	Integer	Number of subscriptions in the segment at its last calculation.
`status`	String	Status of the latest calculation: pending, processing, completed or failed.
`active`	Boolean	Whether a dynamic segment is still recalculated automatically (inactive when unused for a while).
`metrics_pending`	Boolean	Whether the stats of the latest calculation are still being computed (stats then hold the previous ones).
`stats_open_rate`	Number	Average open rate of the subscribers in the segment.
`stats_total_sent`	Integer	Total number of emails sent to the subscribers in the segment.
`stats_percentage_premium_subscribers`	Number	Percentage of subscribers in the segment who are premium in any tier.
`stats_percentage_subscribers_with_referrals`	Number	Percentage of subscribers in the segment who referred at least one subscriber.
`stats_unique_emails_clicked`	Integer	Number of unique emails clicked by subscribers in the segment.
`stats_total_delivered`	Integer	Total number of emails delivered to subscribers in the segment.
`stats_total_referrals`	Integer	Total number of referrals made by subscribers in the segment.
`stats_unsubscribed_rate`	Number	Percentage of subscribers in the segment who unsubscribed.
`stats_total_subscribers`	Integer	Total number of subscribers in the segment.
`stats_clickthrough_rate`	Number	Average click-through rate of the subscribers in the segment.
`stats_unsubscribed_count`	Integer	Number of subscribers in the segment who unsubscribed.
`stats_unique_emails_opened`	Integer	Number of unique emails opened by subscribers in the segment.
`stats_premium_subscribers`	Integer	Number of premium subscribers in the segment.
`stats_average_referrals_per_subscriber`	Number	Average number of referrals per subscriber in the segment.

Segment members

Which subscriptions belong to each segment, as of the segment’s last calculation. Join subscription_id with subscriptions.id.Table: segment_members · Primary key: publication_id, segment_id, subscription_id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`segment_id`	String	Prefixed ID of the segment.
`subscription_id`	String	Prefixed ID of a subscription that belongs to the segment.

Automations

Automations (email workflows) with their journey counts and aggregate email stats.Table: automations · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the automation (aut_…).
`name`	String	Name of the automation.
`status`	String	Status of the automation: running, finishing, inactive, live or draft.
`trigger_events`	Array of strings	Types of events that can trigger the automation.
`description`	String	Description of the automation.
`stats_journeys_running`	Integer	Number of journeys currently in progress.
`stats_journeys_completed`	Integer	Number of completed journeys.
`stats_journeys_total`	Integer	Total number of journeys.
`stats_email_recipients`	Integer	Total number of email recipients of the automation’s emails.
`stats_email_delivered`	Integer	Total number of emails of the automation’s emails delivered.
`stats_email_opens`	Integer	Total number of email opens of the automation’s emails.
`stats_email_unique_opens`	Integer	Number of unique email opens of the automation’s emails.
`stats_email_open_rate`	Number	Percentage of emails of the automation’s emails that were opened.
`stats_email_clicks`	Integer	Total number of email clicks of the automation’s emails.
`stats_email_unique_clicks`	Integer	Number of unique email clicks of the automation’s emails.
`stats_email_click_rate`	Number	Percentage of emails of the automation’s emails that were clicked.
`stats_email_unsubscribes`	Integer	Total number of unsubscribes caused by the automation’s emails.
`stats_email_spam_reports`	Integer	Number of subscribers who reported the automation’s emails as spam.

Automation journeys

Every subscriber’s journey through every automation: when it started, finished or exited.Table: automation_journeys · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the automation journey.
`automation_id`	String	Prefixed ID of the automation.
`subscription_id`	String	Prefixed ID of the subscription going through the automation.
`email`	String	Email address of the subscriber.
`status`	String	Status of the journey: in_progress, completed, exited_early or manually_removed.
`started_at`	Datetime	When the subscriber started the automation (UTC).
`completed_at`	Datetime	When the subscriber finished the automation (UTC).

Automation emails

The emails of every automation step (and A/B variant), with their engagement stats.Table: automation_emails · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Unique ID of the email message.
`automation_id`	String	Prefixed ID of the automation.
`automation_step_id`	String	ID of the automation step this email belongs to.
`automation_step_email_variant_id`	String	ID of the A/B test variant (null for the step’s original email).
`subject_line`	String	Email subject line.
`preview_text`	String	Email preview text.
`status`	String	Status of the email: active (will be sent) or inactive.
`first_sent_at`	Datetime	When the email was first sent (UTC).
`last_sent_at`	Datetime	When the email was last sent (UTC).
`created_at`	Datetime	When the email was created (UTC).
`stats_email_recipients`	Integer	Total number of email recipients of the email.
`stats_email_delivered`	Integer	Total number of emails of the email delivered.
`stats_email_opens`	Integer	Total number of email opens of the email.
`stats_email_unique_opens`	Integer	Number of unique email opens of the email.
`stats_email_open_rate`	Number	Percentage of emails of the email that were opened.
`stats_email_clicks`	Integer	Total number of email clicks of the email.
`stats_email_unique_clicks`	Integer	Number of unique email clicks of the email.
`stats_email_click_rate`	Number	Percentage of emails of the email that were clicked.
`stats_email_unsubscribes`	Integer	Total number of unsubscribes caused by the email.
`stats_email_spam_reports`	Integer	Number of subscribers who reported the email as spam.
`stats_clicks`	String (JSON)	Click statistics per URL in the email (JSON array of objects).

Daily engagements

Opens and clicks per day for each publication, for every email sent (posts and automations).Table: engagements · Primary key: publication_id, date · Sync: Incremental (by date, one bookmark per publication)

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`date`	Date	Day of the metrics (UTC), used as the incremental replication key.
`total_opens`	Integer	Total number of times emails were opened that day.
`unique_opens`	Integer	Number of unique subscribers who opened emails that day.
`total_clicks`	Integer	Total number of link clicks that day.
`total_verified_clicks`	Integer	Total number of link clicks that day verified as human by beehiiv.
`unique_clicks`	Integer	Number of unique subscribers who clicked links that day.
`unique_verified_clicks`	Integer	Number of unique subscribers whose clicks that day were verified as human.

Email blasts

One-off email blasts, active and inactive, with their stats.Table: email_blasts · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the email blast.
`created`	Datetime	When the blast was created (UTC).
`last_sent`	Datetime	When the blast was last sent (UTC).
`status`	String	Status of the blast: active (scheduled to send) or inactive.
`subject_line`	String	Email subject line.
`preview_text`	String	Email preview text.
`stats_email_recipients`	Integer	Total number of email recipients of the blast.
`stats_email_opens`	Integer	Total number of email opens of the blast.
`stats_email_unique_opens`	Integer	Number of unique email opens of the blast.
`stats_email_open_rate`	Number	Percentage of emails of the blast that were opened.
`stats_email_clicks`	Integer	Total number of email clicks of the blast.
`stats_email_unique_clicks`	Integer	Number of unique email clicks of the blast.
`stats_email_click_rate`	Number	Percentage of emails of the blast that were clicked.
`stats_email_unsubscribes`	Integer	Total number of unsubscribes caused by the blast.
`stats_email_spam_reports`	Integer	Number of subscribers who reported the blast as spam.
`stats_clicks`	String (JSON)	Click statistics per URL in the blast (JSON array of objects).

Tiers

Premium (paid) tiers with their prices and number of active subscriptions.Table: tiers · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the tier.
`name`	String	Name of the tier.
`status`	String	Whether the tier has any active price: active or archived.
`description`	String	Description of the tier.
`stats_active_subscriptions`	Integer	Number of active subscriptions in the tier.
`prices`	String (JSON)	Prices of the tier (JSON array of objects with id, currency, amount_cents, enabled, interval, denominator, cta and features).

Custom fields

The custom subscriber fields defined on each publication.Table: custom_fields · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	ID of the custom field.
`kind`	String	Type of value stored in the field: string, integer, boolean, date, datetime, list or double.
`display`	String	Display name of the custom field.
`created`	Datetime	When the custom field was created (UTC).
`options`	String (JSON)	Allowed option values, only for list fields (JSON array).

Newsletter lists (sub-newsletters subscribers opt in to).Table: newsletter_lists · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the newsletter list.
`name`	String	Name of the newsletter list.
`slug`	String	URL-friendly slug of the newsletter list.
`description`	String	Description of the newsletter list.
`status`	String	Status of the newsletter list: draft, active or archived.
`auto_subscribe`	Boolean	Whether new subscribers are subscribed to this list automatically.
`show_in_preference_center`	Boolean	Whether the list appears on the subscriber’s Manage Preferences page.
`subscriber_count`	Integer	Number of active subscribers on the list.
`created_at`	Datetime	When the list was created (UTC).
`updated_at`	Datetime	When the list was last updated (UTC).
`from_address`	String	From address of posts sent to this list.
`reply_to_address`	String	Reply-to address of posts sent to this list.
`sender_name`	String	Sender name preset of posts sent to this list.
`headers`	String (JSON)	Custom email headers of the list (JSON object).
`utm_source`	String	utm_source appended to links in posts sent to this list.
`utm_medium`	String	utm_medium appended to links in posts sent to this list.
`utm_campaign`	String	utm_campaign appended to links in posts sent to this list.
`utm_params_enabled`	Boolean	Whether UTM parameters are appended to links in posts sent to this list.
`tier_ids`	Array of strings	Prefixed IDs of the paid tiers that gate this list.

Which subscriptions joined each newsletter list, and when they joined and left.Table: newsletter_list_subscriptions · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the newsletter list subscription.
`newsletter_list_id`	String	Prefixed ID of the newsletter list.
`subscription_id`	String	Prefixed ID of the subscription.
`status`	String	Status of the subscription to the list: pending, active, inactive or paused.
`subscribed_at`	Datetime	When the subscription to the list was activated (UTC).
`unsubscribed_at`	Datetime	When the subscription to the list was deactivated (UTC).
`created_at`	Datetime	When the list subscription was created (UTC).

Authors

Authors (users and guest authors) available to the posts.Table: authors · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the author (user_… or guest_…).
`type`	String	Author type: user or guest_author.
`name`	String	Display name of the author.
`bio`	String	Biography of the author.
`bio_image_url`	String	Profile image URL of the author.
`social_media_links`	String (JSON)	Social media links of the author (JSON object).

Polls

Polls (voting and trivia) with their choices and vote counts.Table: polls · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the poll.
`name`	String	Name of the poll.
`question`	String	Question of the poll.
`description`	String	Description of the poll.
`poll_type`	String	Type of poll: voting or trivia.
`status`	String	Status of the poll: draft or published.
`created_at`	Datetime	When the poll was created (UTC).
`poll_choices`	String (JSON)	Choices of the poll (JSON array of objects with id and label).
`stats_completions`	Integer	Total number of responses to the poll.
`stats_vote_counts`	String (JSON)	Number of votes per choice label (JSON object).

Poll responses

Every subscriber response to every poll, with the post where it was collected.Table: poll_responses · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Unique ID of the poll response.
`poll_id`	String	Prefixed ID of the poll.
`subscription_id`	String	Prefixed ID of the subscription that responded (null if the subscription was permanently deleted).
`subscription_deleted`	Boolean	Whether the responding subscription has been deleted.
`poll_choice_id`	String	ID of the selected choice.
`poll_choice_label`	String	Label of the selected choice.
`created_at`	Datetime	When the response was submitted (UTC).
`extended_feedback`	String	Free-text feedback left by the subscriber.
`post_id`	String	Prefixed ID of the post where the response was collected.
`post_title`	String	Title of the post where the response was collected.
`post_publish_date`	Datetime	Scheduled publication date of that post (UTC).

Podcasts

Podcasts hosted on beehiiv.Table: podcasts · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the podcast.
`created`	Datetime	When the podcast was created (UTC).
`title`	String	Title of the podcast.
`slug`	String	URL slug of the podcast.
`description`	String	Description of the podcast.
`categories`	Array of strings	Categories of the podcast in display order (subcategories include the parent, e.g. News-Politics).
`artwork_url`	String	URL of the podcast artwork.
`status`	String	Status of the podcast: draft, live or archived.
`language`	String	ISO 639-1 language code of the podcast.
`author`	String	Author of the podcast.
`type`	String	Podcast type: episodic or serial.
`imported`	Boolean	Whether the podcast was created by an import.
`copyright`	String	Copyright text of the podcast.
`publishing_frequency`	Integer	Most common interval, in days, between published episodes.
`website_url`	String	Website URL of the podcast.
`explicit`	Boolean	Whether the podcast is marked as explicit.
`platform_links`	String (JSON)	Distribution URLs per platform such as apple, spotify or youtube (JSON object).

Podcast episodes

Episodes of every podcast.Table: podcast_episodes · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the episode.
`podcast_id`	String	Prefixed ID of the podcast the episode belongs to.
`created`	Datetime	When the episode was created (UTC).
`updated`	Datetime	When the episode was last updated (UTC).
`title`	String	Title of the episode.
`slug`	String	Web slug of the episode.
`publish_date`	Datetime	When the episode actually went live (UTC).
`displayed_date`	Datetime	Date displayed for the episode (UTC).
`duration`	Integer	Duration of the episode audio in seconds.
`description`	String	Plain-text summary of the show notes (up to 255 characters).
`show_notes`	String	Full HTML show notes of the episode.
`artwork_url`	String	URL of the episode artwork.
`status`	String	Status of the episode: draft, scheduled, published or archived.
`season_number`	Integer	Season number of the episode.
`episode_number`	Integer	Episode number within the season.
`audio_url`	String	Public streaming URL of the episode audio.
`transcript_url`	String	WebVTT transcript URL of the episode.

Referral program milestones

Milestones of the referral program and their rewards.Table: referral_program_milestones · Primary key: publication_id, id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`id`	String	Prefixed ID of the milestone.
`num_referrals`	Integer	Number of referrals needed to reach the milestone.
`auto_fulfill`	Boolean	Whether the reward email is sent automatically when the milestone is reached (promo code rewards).
`reward_id`	String	Prefixed ID of the reward.
`reward_name`	String	Name of the reward.
`reward_description`	String	Description of the reward.
`reward_image_url`	String	Image URL of the reward.
`reward_type`	String	Type of reward: physical, promo_code, digital or premium_gift.

Ad network reports

Ad network performance and payments: one row per advertisement link per post. Only for publications in the beehiiv Ad Network.Table: ad_network_reports · Primary key: publication_id, post_id, ad_link_id · Sync: Full table

Field	Type	Description
`publication_id`	String	Prefixed ID of the beehiiv publication the record belongs to (pub_…).
`post_id`	String	Prefixed ID of the post that contained the advertisement.
`ad_link_id`	String	ID used to attribute engagement events to the advertisement.
`ad_link`	String	URL of the advertisement.
`opens`	Integer	Approved number of unique opens.
`payable_clicks`	Integer	Number of clicks approved for payment.
`revenue`	String	Revenue approved for payment, formatted by beehiiv (e.g. $12.34).
`revenue_amount`	Number	Revenue approved for payment as a number (parsed from revenue).
`is_programmatic`	Boolean	Whether the advertisement was placed through a programmatic ad slot instead of an on-demand offer.

Implementation notes

Page limit of the beehiiv API: lists that beehiiv pages by number (posts, segment members, segments and others) can be read up to page 100, that is 10,000 rows per list. A list beyond that fails its table with a message in the log instead of loading part of it. In practice, a segment with more than 10,000 members makes Segment members fail: deselect that table if you have such a segment.
Schedule: most tables are read whole on every sync, so a daily sync is recommended.
Segment members reflect the last calculation of each segment; dynamic segments are recalculated by beehiiv about once a day.
Ad network revenue comes formatted by beehiiv (for example $12.34) in revenue; revenue_amount holds the same value as a number.
Deleted records: records deleted in beehiiv disappear from the Full table tables on the next sync.

Get started

Context

Activate

Organizations

Workspaces

Resources

beehiiv as a data source

Configuring beehiiv as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Available streams

Tables that depend on a beehiiv feature

Fields by stream

Implementation notes