Get publication engagements
list_engagementsRetrieve engagement metrics for a Beehiiv publication, filtered by date range, email type, and reporting granularity.
Instructions
Get publication engagements. Reads account data. OAuth integrations require publications:read.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"publication_id": "<publication_id>"
},
"name": "list_engagements"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from BEEHIIV_ACCOUNTS. Defaults to BEEHIIV_DEFAULT_ACCOUNT or the first configured account. | |
| direction | No | The direction that the results are sorted in. Defaults to `asc`. `asc`: Oldest to newest `desc`: Newest to oldest | asc |
| email_type | No | Filter engagement metrics by email type. If omitted, all email engagement is included. `post`: Only post emails. `message`: Only automated and system-generated emails. | |
| start_date | No | The starting date for the engagement metrics in `YYYY-MM-DD` format. Defaults to 1 day ago if not provided. | |
| granularity | No | The granularity at which to report the engagement metrics. Defaults to `day` if not provided. | |
| number_of_days | No | 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. | |
| publication_id | Yes | The prefixed ID of the publication. |