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

List segment subscriber IDs OAuth Scope: segments:read

GET
https://api.beehiiv.com/v2/publications/:publicationId/segments/:segmentId/results
GET
/v2/publications/:publicationId/segments/:segmentId/results
$curl https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/segments/seg_00000000-0000-0000-0000-000000000000/results \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json"
1{
2  "data": [
3    "sub_8a7f3c2e-4d1b-4f9a-9c3e-2b7d5f6a1e23",
4    "sub_3b9f1d7a-2c4e-4a8f-bd5e-9f7c3a1b2d45"
5  ],
6  "limit": 50,
7  "page": 1,
8  "total_results": 125,
9  "total_pages": 3
10}
List subscriber IDs for a segment. Returns a lightweight array of subscription IDs only, without additional subscriber details. **Use this endpoint when you only need subscriber IDs** (e.g., for counting, ID-based lookups, or integrations with external systems). If you need full subscriber details (email, status, custom fields, etc.), use `/segments/{segmentId}/members` instead.
Was this page helpful?
Previous

Delete segment OAuth Scope: segments:write

Next
Built with

List subscriber IDs for a segment. Returns a lightweight array of subscription IDs only, without additional subscriber details. Use this endpoint when you only need subscriber IDs (e.g., for counting, ID-based lookups, or integrations with external systems). If you need full subscriber details (email, status, custom fields, etc.), use /segments/{segmentId}/members instead.

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

limitintegerOptional
A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.
pageintegerOptional

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.

Response

OK
datalist of strings
An array of subscription ids
limitinteger
The limit placed on the results. If no limit was specified in the request,this defaults to 10.
pageinteger>=0Defaults to 1
The page number the results are from. If no page was specified in the request, this defaults to page 1.
total_resultsinteger
The total number of results from all pages.
total_pagesinteger
The total number of pages.

Errors

400
Bad Request Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error