> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# beehiiv as a data source

> Bring your beehiiv publications, subscribers, posts with stats, segments, automations, daily engagement and more to Nekt.

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.

> [!NOTE]
>
> The connector only reads data. It never creates, changes or deletes anything in beehiiv.

## Configuring beehiiv as a Source

In the [Sources](https://app.nekt.ai/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.

> [!TIP]
>
> 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](https://docs.nekt.com/runs/scheduling-and-triggers.md), 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](https://docs.nekt.com/get-started/core-concepts/resource-control).

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/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 |

> [!NOTE]
>
> 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.

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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). |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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). |

> [accordion] 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). |

> [accordion] 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. |

> [accordion] 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). |

> [accordion] 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). |

> [accordion] 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). |

> [accordion] Newsletter lists
>
> 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. |

> [accordion] Newsletter list subscriptions
>
> 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). |

> [accordion] 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). |

> [accordion] 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). |

> [accordion] 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). |

> [accordion] 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). |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.