> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.beehiiv.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.beehiiv.com/_mcp/server.
# Get publication engagements OAuth Scope: publications:read
GET https://api.beehiiv.com/v2/publications/{publicationId}/engagements
Retrieve email engagement metrics for a specific publication over a defined date range and granularity. By default, the endpoint returns metrics for the past day, aggregated daily. The max number of days allowed is 31. All dates and times are in UTC.
Reference: https://developers.beehiiv.com/api-reference/engagements/index
## Authentication
- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token.
## Request
### Path parameters
- `publicationId` (string, required) — The prefixed ID of the publication.
### Query parameters
- `start_date` (date, optional) — The starting date for the engagement metrics in `YYYY-MM-DD` format. Defaults to 1 day ago if not provided.
- `number_of_days` (integer, optional) — The number of days to return engagement metrics for, starting from `start_date`. Must be between 1 and 31. Defaults to `1` if not provided.
- `granularity` (enum, optional) — The granularity at which to report the engagement metrics. Defaults to `day` if not provided.
- Allowed values: `day`, `week`, `month`
- `email_type` (enum, optional) — Filter engagement metrics by email type. If omitted, all email engagement is included. `post`: Only post emails. `message`: Only automated and system-generated emails.
- Allowed values: `all`, `post`, `message`
- `direction` (enum, optional, default: asc) — The direction that the results are sorted in. Defaults to `asc`. `asc`: Oldest to newest `desc`: Newest to oldest
- Allowed values: `asc`, `desc`
## Response
### 200
OK
- `data` (list of PublicationEngagementMetrics, required) — The list of engagement metrics for the publication within the specified date range and granularity. Returns an empty list if there is no engagement data for the specified period.
- `publication_id` (string, required) — The unique identifier of the publication. Passed as a path parameter in the request.
- `granularity` (enum, required) — The granularity at which the engagement metrics are reported.
- Allowed values: `day`, `week`, `month`
- `email_type` (enum, required) — The email type filter applied to the engagement metrics. Defaults to `all`.
- Allowed values: `all`, `post`, `message`
- `start_date` (date, required) — The starting date of the engagement metrics.
- `number_of_days` (integer, required) — The number of days of engagement metrics returned.
## Errors
### 400 Bad Request Error
Bad Request
- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)
### 401 Unauthorized Error
Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)
### 404 Not Found Error
Resource Not Found
- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)
### 429 Too Many Requests Error
Rate Limit Exceeded
- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)
### 500 Internal Server Error
Internal Server Error
- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)
## Types
### PublicationEngagementMetrics
- `date` (date, required) — The starting date of the period for which the engagement metrics are reported based on the selected granularity. `day` granularity: The specific day. `week` granularity: The Monday of the week. `month` granularity: The first day of the month.
- `total_opens` (integer, required) — The total number of times emails were opened during the period.
- `unique_opens` (integer, required) — The number of unique subscribers who opened emails during the period.
- `total_clicks` (integer, required) — The total number of times links were clicked during the period.
- `total_verified_clicks` (integer, required) — The total number of times links were clicked, during the period, as verified by our system.
- `unique_clicks` (integer, required) — The number of unique subscribers who clicked links during the period.
- `unique_verified_clicks` (integer, required) — The number of times links were clicked by unique subscribers, during the period, as verified by our system.
### ErrorDetail
- `message` (string, required)
- `code` (string, required)
## Examples
**Response**
```json
{
"data": [
{
"date": "2025-01-01",
"total_opens": 150,
"unique_opens": 120,
"total_clicks": 75,
"total_verified_clicks": 70,
"unique_clicks": 60,
"unique_verified_clicks": 55
}
],
"publication_id": "pub_ad76629e-4a39-43ad-8055-0ee89dc6db15",
"granularity": "day",
"email_type": "all",
"start_date": "2025-01-01",
"number_of_days": 1
}
```
**SDK Code**
```python
import requests
url = "https://api.beehiiv.com/v2/publications/pub_ad76629e-4a39-43ad-8055-0ee89dc6db15/engagements"
headers = {"Authorization": "Bearer "}
response = requests.get(url, headers=headers)
print(response.json())
```
```javascript
const url = 'https://api.beehiiv.com/v2/publications/pub_ad76629e-4a39-43ad-8055-0ee89dc6db15/engagements';
const options = {method: 'GET', headers: {Authorization: 'Bearer '}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.beehiiv.com/v2/publications/pub_ad76629e-4a39-43ad-8055-0ee89dc6db15/engagements"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer ")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://api.beehiiv.com/v2/publications/pub_ad76629e-4a39-43ad-8055-0ee89dc6db15/engagements")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer '
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.get("https://api.beehiiv.com/v2/publications/pub_ad76629e-4a39-43ad-8055-0ee89dc6db15/engagements")
.header("Authorization", "Bearer ")
.asString();
```
```php
request('GET', 'https://api.beehiiv.com/v2/publications/pub_ad76629e-4a39-43ad-8055-0ee89dc6db15/engagements', [
'headers' => [
'Authorization' => 'Bearer ',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://api.beehiiv.com/v2/publications/pub_ad76629e-4a39-43ad-8055-0ee89dc6db15/engagements");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer ");
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = ["Authorization": "Bearer "]
let request = NSMutableURLRequest(url: NSURL(string: "https://api.beehiiv.com/v2/publications/pub_ad76629e-4a39-43ad-8055-0ee89dc6db15/engagements")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```