Get aggregate stats <Badge intent="info" minimal outlined>OAuth Scope: posts:read</Badge>

GET

https://api.beehiiv.com/v2/publications/:publicationId/posts/aggregate_stats

GET

/v2/publications/:publicationId/posts/aggregate_stats

curl https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts/aggregate_stats \
     -H "Authorization: Bearer <token>"

{
  "data": {
    "stats": {
      "email": {
        "recipients": 100,
        "delivered": 100,
        "opens": 50,
        "unique_opens": 45,
        "open_rate": 45,
        "clicks": 10,
        "unique_clicks": 8,
        "verified_clicks": 9,
        "unique_verified_clicks": 7,
        "click_rate": 8,
        "unsubscribes": 1,
        "spam_reports": 1
      },
      "web": {
        "views": 200,
        "clicks": 40
      },
      "clicks": [
        {
          "url": "https://www.google.com",
          "base_url": "https://www.google.com",
          "email": {
            "clicks": 10,
            "unique_clicks": 8,
            "verified_clicks": 9,
            "unique_verified_clicks": 7,
            "click_through_rate": 80
          },
          "web": {
            "clicks": 40,
            "unique_clicks": 40,
            "click_through_rate": 20
          },
          "total_clicks": 50,
          "total_unique_clicks": 48,
          "total_click_through_rate": 40
        }
      ],
      "upgrades": 5
    },
    "computed_at": 1700000000
  }
}

Retrieve aggregate stats for all posts.

The clicks breakdown returns the top 1,000 URLs by total clicks across the matched posts, and URLs that differ only by a per-subscriber UUID (polls, preference pages, etc.) are grouped into a single row.

Stats for large publications are served from a cache that is refreshed in the background about once an hour; computed_at is when the returned numbers were calculated.

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

audienceenumOptionalDefaults to all

Optionally filter the results by audience

Allowed values:

platformenumOptionalDefaults to all

Optionally filter the results by platform.
web - Posts only published to web.
email - Posts only published to email.
both - Posts published to email and web.
all - Does not restrict results by platform.

Allowed values:

statusenumOptionalDefaults to all

Optionally filter the results by the status of the post.
draft - not been scheduled.
confirmed - The post will be active after the scheduled_at.
archived - The post is no longer active.
all - Does not restrict results by status.

Allowed values:

content_tags[]list of stringsOptional

Optionally filter posts by content_tags. Adding a content tag will return any post with that content tag associated to it.
Example: Filtering for content_tags: ["sales","closing"] will return results of posts that have either sales or closing content_tags.

authors[]list of stringsOptional

Optionally filter posts by their authors. Adding an author name will return any post with that author associated to it (case-insensitive).

Example: Filtering for authors: ["John Doe","Jane Smith"] will return results of posts that have either John Doe or Jane Smith as authors.

hidden_from_feedenumOptionalDefaults to all

Optionally filter the results by the hidden_from_feed attribute of the post.
all - Does not restrict results by hidden_from_feed.
true - Only return posts hidden from the feed.
false - Only return posts that are visible on the feed.

Allowed values:

Response

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error