# List a newsletter's subscriber insights **GET /newsletters/{newsletter}/insights** Per subscriber engagement scoring. Each row blends what a reader did in the newsletter's community with what its email provider reported about them, carries a fourteen day over fourteen day velocity, and lands on a lifecycle status. It is the object a CRM or a re engagement automation reads, and the one thing in this catalog no email provider can answer, because half the signal never reaches it. Scores are recomputed by a scheduled pass rather than at read time, so a row is only as fresh as the last pass, and `last_action_at` can be newer than the score that reflects it. Only people with a Commune account are scored, because engagement is attributed to an account. Someone the newsletter knows only as an email address has no row here and is absent from this collection rather than present with a zero score, so the size of this collection is not the size of the audience. `status` is assigned by rank within the newsletter, not by an absolute score, so it moves when the people around a reader move even if that reader did nothing. Ordered by `total_score` descending, so the first page is the newsletter's most engaged readers. Creator scope, and the one read Commune may put behind a plan: a key without it answers `402`. ## Servers - Production. There is no separate sandbox host. : https://api.usecommune.com (Production. There is no separate sandbox host. ) ## Authentication methods - Api key ## Parameters ### Headers - **Commune-Version** (string(date)) The contract version this request is written against, as a release date (`YYYY-MM-DD`). Omitting the header pins the request to the version that was current when the API key was issued, so an integration keeps working when a newer version ships. An unknown value answers `400` with `invalid_version`. ### Path parameters - **newsletter** (string) The newsletter's `id` (a UUID) or its `handle`. A handle is unique across Commune and is the identifier its public web profile uses, so it is the one to hardcode in an integration. ### Query parameters - **cursor** (string) The `pagination.next_cursor` value from the previous page. Omit it to read the first page. A cursor is opaque, is only valid for the same operation with the same filters, and is not a durable identifier. - **limit** (integer) How many items to return in this page. This is a page size, not an offset. Fewer items than requested may come back and that does not mean the collection is exhausted, only an absent `next_cursor` does. - **expand** (string) 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`. One accepted path is not a relationship. `?expand=content` on `GET /articles/{article}` adds the Markdown rendition of the body beside the HTML one. It is the same trade the parameter always offers, a fuller response for a larger one, over a property that has more than one representation rather than over a reference. - **fields** (string) 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`. A trimmed body is a subset of the schema this operation declares, and a property that schema marks required is absent when it was not asked for. That is the point of the parameter, so a client that validates responses against the schema either sends no `fields` or relaxes `required`. - **status** (string) Return only subscribers in this lifecycle status. Repeat the parameter to accept several. - **velocity** (string) Return only subscribers whose engagement is moving this way. Repeat the parameter to accept several. ## Responses ### 200 A page of subscriber insights, highest scoring first. #### Body: application/json (object) - **object** (string) Always `list`, so a response is self describing. - **data** (array) This page of items, in the order the operation documents. - **pagination** (object) Cursor pagination state. Commune never exposes an offset or a page number: a collection is a moving window, and an offset silently skips or repeats items when the window shifts between two requests. ### 400 The request was malformed: an unknown query parameter, an unparseable cursor, an unknown `expand` path, or an unrecognised `Commune-Version`. #### Body: application/json (object) - **error** (object) ### 401 No API key was presented, or the key is unknown, revoked or expired. All four answer identically, down to the wording. Saying that a key was revoked rather than never issued confirms to whoever is holding the string that it was once real, which a legitimate caller does not need and a thief should not get. #### Headers - **WWW-Authenticate** (string) The authentication scheme this API accepts. Always `Bearer realm="Commune API"`; there is no second scheme and no query-parameter fallback, because a credential that can travel in a URL ends up in access logs and referer headers. #### Body: application/json (object) - **error** (object) ### 402 The key is allowed to read this but its plan does not include it. Insights is the one read surface Commune reserves the right to meter, because its numbers are computed rather than looked up: the scores and the event stream behind them are the expensive half of the catalog and the half no email provider can answer. Every other read stays free. #### Body: application/json (object) - **error** (object) ### 403 The key is valid but is not allowed to read this. Either it carries public scope and the operation needs creator scope, or it is bound to a different newsletter than the one addressed. #### Body: application/json (object) - **error** (object) ### 404 No such resource, or the key is not allowed to know that it exists. Commune answers `404` rather than `403` where distinguishing the two would leak the existence of private content. #### Body: application/json (object) - **error** (object) ### 429 Too many requests. Back off and retry after the interval named by the `Retry-After` response header. #### Headers - **Retry-After** (integer) Seconds to wait before retrying. #### Body: application/json (object) - **error** (object) ### 500 Something failed inside Commune. The request may be retried. #### Body: application/json (object) - **error** (object) [Powered by Bump.sh](https://bump.sh)