Retrieve one newsletter metric bucketed over time
One metric, bucketed, for charting. Every other operation in this domain answers with a snapshot, which is the wrong shape for a line, so this one returns the series behind it.
Name the quantity with metric and the bucket width with interval. Buckets are contiguous, and a bucket in which nothing happened comes back with a value of 0 rather than being omitted, so a client can plot the array without filling the gaps itself.
subscribers counts subscriptions Commune recorded in each bucket, not the running audience size, and it inherits the partial cache caveat that applies wherever Commune counts the subscribers of a newsletter connected to an outside provider. sends counts the dispatches Commune performed and is never a count of every email the newsletter has sent, because an imported article was mailed by the provider before Commune saw it.
Needs insights: read. threads and messages depend on whether the key acts for the newsletter, which a key does when it holds write in any family. Such a key counts every conversation. A key that holds only read permissions counts public conversations and the replies in them, which leaves out an article's own discussion, visible to subscribers only. The other four metrics are the same for both kinds of key.
Request
- Base URL: https://api.usecommune.com
- URL: https://api.usecommune.com/newsletters/{newsletter}/timeseries
- Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://usecommune.com/api/oauth/authorize, token URL https://usecommune.com/api/oauth/token, scopes: insights:read)
Query parameters
Comma-separated list of relationship paths to inline in the response. Unexpanded relationships are returned as a reference object carrying only id and object. Each operation documents the paths it accepts, and an unknown path answers 400. Nested paths use a dot, for example article.newsletter.
Comma-separated allow-list of top level properties to return on each object, so a client can trim a response it does not need in full. id and object are always returned. An unknown property name answers 400. Properties omitted by an operation, such as content on any article list, cannot be brought back with fields.
Start of the window, inclusive, as a date or an RFC 3339 timestamp. Giving this overrides period. A since later than until answers 400. Anything that is neither of those two shapes answers 400 as well, rather than being guessed at: a lenient parser would read 8/1/2026 as a date and give two callers different windows for the same string.
End of the window, exclusive, as a date or an RFC 3339 timestamp. Defaults to now. Only meaningful alongside since.
Which quantity a series buckets. Each value is a count of things that happened inside a bucket, never a running total, so a client that wants a cumulative line adds them up itself.
Which quantity to bucket. Exactly one per request.
How wide each bucket is. A week starts on Monday and a month on the first, both in UTC, so buckets line up across two newsletters in different time zones.
How wide each bucket is. Defaults to day. A week starts on Monday and a month on the first, both in UTC.
Response
The requested metric, bucketed over the resolved window.
Example response
{
"newsletter": {
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
}
}Changes
No recorded changes to this operation across all 1 revision of this API.