How to get your beehiiv API key (and what you can read with it)
Where to find your beehiiv API key and publication ID, how to test the v2 API with curl, and which subscriber stats it returns — open rate, click rate, and active subscriptions.
The beehiiv API gives you programmatic read access to the numbers you normally check in the beehiiv dashboard: active subscriptions, premium subscriptions, average open rate, average click rate, and total emails sent. Read access is included on every plan — the free Launch tier too.
You need two values: an API key and your publication ID. Both live on the same settings page.
Get the API key
- Sign in at app.beehiiv.com
- Go to Settings → Workspace → API
- If you see "Verify your identity to create an API key", complete that first — see below
- Click New API key, give it a name, and copy the key
- On the same page, copy your publication ID — it starts with
pub_
The identity check
beehiiv gates API key creation behind a Stripe Identity verification (they quote under five minutes). There's no way around it — the key button stays locked until it's done.
Worth knowing: the publication ID is visible without verifying. It sits in its own card on the same page, so you can copy your pub_… ID immediately and still have no key. That half-finished state looks like a bug and isn't — the two values are gated differently.
Treat the key like a password: it grants access to your subscriber counts and campaign stats, so keep it out of client-side code and git history. If it ever leaks, delete it on the same page and create a new one.
Test it with curl
The v2 API authenticates with a bearer header. This returns your first publication and confirms the key works:
curl -s "https://api.beehiiv.com/v2/publications?limit=1" \
-H "Authorization: Bearer YOUR_API_KEY"To pull the actual stats, request your publication with the stats expansion:
curl -s "https://api.beehiiv.com/v2/publications/pub_XXXXXXXX?expand[]=stats" \
-H "Authorization: Bearer YOUR_API_KEY"The response includes a stats object:
{
"data": {
"name": "My Newsletter",
"stats": {
"active_subscriptions": 1482,
"active_premium_subscriptions": 37,
"average_open_rate": 46.1,
"average_click_rate": 8.3,
"total_sent": 52210
}
}
}One thing to know: beehiiv lets you disable individual stats, and a disabled stat comes back as false instead of a number — handle that if you're parsing the response yourself.
Put your subscriber count on a public page
Subscriber count is one of the most-shared metrics in the build-in-public world — and screenshots of it go stale the moment you post them. If you'd rather have a live number, infra.page has a beehiiv widget: paste the API key, enter your pub_… ID, and your subscriber count, open rate, and click rate update on a public page you can link from anywhere. You choose what stays public — show growth only, or hide a stat entirely.
Setting up other tools too? See how to create a read-only Stripe key and a Sentry auth token with the right scopes.
Related Posts
How to get an Ahrefs API key (the free Domain Rating endpoint now needs one)
Ahrefs' free Domain Rating API requires authentication from 10 August 2026. How to get a free API key, test it with curl, and meet the attribution rule most DR tools are missing.
How to create a Sentry auth token (with the right scopes)
Step-by-step: create a Sentry auth token, pick the minimal read-only scopes (project:read, event:read, org:read), test it with curl, and use it with self-hosted Sentry.
How to create a restricted Stripe API key (read-only)
Create a Stripe restricted key that can only read subscriptions and prices: step-by-step permissions, test vs live mode, a curl test, and why you should never hand out sk_ keys.