beehiiv Developer Documentation

curl -G https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/exports/subscriptions \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d limit=10

{
  "data": [
    {
      "id": "export_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "variant": "full",
      "status": "completed",
      "publication_id": "pub_9f8e7d6c-5b4a-3210-fedc-ba9876543210",
      "failure_reason": "",
      "download_url": "https://cdn.beehiiv.com/exports/pub_9f8e7d6c-5b4a-3210-fedc-ba9876543210/subscribers_20240702.csv",
      "completed": 1719941400,
      "created": 1719938400,
      "updated": 1719941400
    }
  ],
  "limit": 10,
  "has_more": true,
  "next_cursor": "eyJ0aW1lc3RhbXAiOiIyMDI0LTA3LTAyVDE3OjMwOjAwLjAwMDAwMFoifQ=="
}

This is a gated feature that requires enablement. Contact support to enable Subscription Export API access for your publication.

Returns a list of Subscription Export objects for a publication. Newest first.

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

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.

cursorstringOptional

Cursor-based pagination (recommended): Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination. See the Pagination Guide for more details.

pageintegerOptional

Offset-based pagination (deprecated): Page number for offset-based pagination. This method is deprecated and limited to 100 pages maximum. Please migrate to cursor-based pagination using the cursor parameter. If not specified, results 1-10 from page 1 will be returned. See the Pagination Guide for migration guidance.

Response

datalist of objectsOptional

An array of Subscription Export objects

limitintegerOptional

The number of results returned in this page.

pageintegerOptional>=0Defaults to 1

Offset pagination only: The page number the results are from. Only present when using deprecated offset-based pagination.

total_pagesintegerOptional

Offset pagination only: The total number of pages. Only present when using deprecated offset-based pagination.

has_morebooleanOptional

Cursor pagination only: Indicates whether there are more results available after the current page. Only present when using cursor-based pagination.

next_cursorstringOptional

Cursor pagination only: The cursor token to use for fetching the next page of results. This will be null if has_more is false. Only present when using cursor-based pagination.

total_resultsintegerOptional

Mixed pagination: The total number of results from all pages. For offset-based pagination, this is always included.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error