Metrics

Retrieve a newsletter's acquisition breakdown

Where a newsletter's new subscribers came from over a window: the split by the import that brought them in, and how the invite funnel performed.

by_source is about imports. It groups on the value an import stamped, so migrating a newsletter between providers later never relabels the history: a value that is already set is never overwritten. For whether somebody subscribed through Commune at all, read source on the subscriber, which is a different question with a different answer.

The counts here are arrivals Commune recorded inside the window and are not the newsletter's audience size. For a newsletter connected to an outside provider they also miss anyone who joined at the provider between two imports.

get/newsletters/{newsletter}/growth

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/newsletters/{newsletter}/growth
  • 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

expandstring

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.

fieldsstring

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.

period'7d' | '14d' | '30d' | '90d' | '6m' | '1y' | 'all'

A named window, counted back from today in UTC. Defaults to 30d. Ignored when since is given, so a request never has to reconcile two conflicting windows.

sincestring

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.

untilstring

End of the window, exclusive, as a date or an RFC 3339 timestamp. Defaults to now. Only meaningful alongside since.

Response

The acquisition breakdown for the resolved window.

object'newsletter_growth' required

Always newsletter_growth.

period_startstring date-time required

Start of the resolved window, inclusive.

period_endstring date-time required

End of the resolved window, exclusive.

Example response

{
  "newsletter": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "by_source": [
    {
      "source": "kit"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.