For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
LoginStart trialGet a demo
  • Welcome
    • Getting Started
    • Create an API Key
    • Pagination
    • Rate Limiting
    • No-Code Integrations
  • Webhooks
  • OAuth2
  • API Reference
      • POSTCreate segment
      • GETList segments <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>
      • GETGet segment <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>
      • PUTRecalculate segment <Badge intent="info" minimal outlined>OAuth Scope: segments:write</Badge>
      • GETList segment subscribers <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>
      • GETList segment subscriber IDs <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>
      • DELDelete segment <Badge intent="info" minimal outlined>OAuth Scope: segments:write</Badge>
LogoLogo
LoginStart trialGet a demo
API ReferenceSegments

Get segment OAuth Scope: segments:read

GET
https://api.beehiiv.com/v2/publications/:publicationId/segments/:segmentId
GET
/v2/publications/:publicationId/segments/:segmentId
$curl https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/segments/seg_00000000-0000-0000-0000-000000000000 \
>     -H "Authorization: Bearer <token>"
1{
2  "data": {
3    "id": "seg_00000000-0000-0000-0000-000000000000",
4    "name": "My Segment",
5    "type": "dynamic",
6    "total_results": 15,
7    "status": "completed",
8    "active": true,
9    "last_calculated": 1666800076,
10    "stats": {
11      "open_rate": 0.5,
12      "total_sent": 100,
13      "percentage_premium_subscribers": 0.2,
14      "percentage_subscribers_with_referrals": 0.1,
15      "unique_emails_clicked": 10,
16      "total_delivered": 100,
17      "total_referrals": 10,
18      "unsubscribed_rate": 0.05,
19      "total_subscribers": 100,
20      "clickthrough_rate": 0.5,
21      "unsubscribed_count": 5,
22      "unique_emails_opened": 10,
23      "premium_subscribers": 20,
24      "average_referrals_per_subscriber": 0.1
25    }
26  }
27}
Retrieve information about a specific segment belonging to a publication
Was this page helpful?
Previous

Recalculate segment OAuth Scope: segments:write

Next
Built with

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"
The prefixed ID of the publication object
segmentIdstringRequiredformat: "^(seg_[0-9a-fA-F\-]+)$"
The prefixed ID of the segment object

Query parameters

expand[]list of enumsOptional

Optionally expand the response to include additional data.
stats - Requests the most recently calculated statistics for a segment.
Segment stats are recalculated once daily around 7 a.m. UTC for dynamic segments, but can be manually recalculated at any time in the dashboard. Manual and static segments only calculate once upon upload or creation.

Allowed values:

Response

OK
dataobject
The segment object. To expand results, see the results endpoint.

Errors

404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error