# Retrieve the RFM summary

Source: https://kirora.io/docs/api/reference/getRfmSummary

`GET /v1/reports/rfm`

Requires an API key with the `reports:read` scope. [About keys and scopes](https://kirora.io/docs/api/reference/authentication)

Works with integration, agent and partner keys.

Returns the workspace's RFM summary: how many customers its RFM groups (`rfm` on each contact, `rfmGroup` in segment rules) were scored from, how many each group holds, and when. RFM groups customers by the recency, frequency and monetary value of their purchases. Scoring runs once a day.

## Header parameters

- `Kirora-Workspace` (string, optional, pattern `^[A-Za-z0-9._:-]{1,128}$`) — Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

## Returns

Returns `200 OK` with a `RfmSummary` in `data`. Otherwise returns an error; [Errors](https://kirora.io/docs/api/reference/errors) lists every code and which to retry.

- `customers` (integer | null, required, min 0) — The customers (contacts with the workspace's purchase event) the last scoring placed in a group; `null` until first scored. Groups rest on these alone, with no minimum: a few customers make coarse groups.
- `purchaseEvent` (string | null, required) — The purchase event the last scoring counted (the workspace's `purchaseEvent` then); `null` until first scored.
- `currency` (string | null, required) — The workspace's main currency, the one most purchases carry: what `monetary` and each contact's `totalSpent` count in. `null` when purchases carry no currency or no amount, or until first scored.
- `scoredAt` (string | null, required, date-time) — When the groups were last scored (once a day); `null` until first.
- `groups` (map<string, integer> | null, required, keys: one of `champions`, `loyal`, `cant_lose_them`, `potential_loyalists`, `new_customers`, `need_attention`, `about_to_sleep`, `at_risk`, `hibernating`, `lost`, values: min 0) — How many customers each group holds, every group listed (an empty one as 0); `null` until first scored.

## Example

```bash
curl https://api.kirora.io/v1/reports/rfm \
  -H "Authorization: Bearer $KIRORA_API_KEY"
```

Response `200`:

```json
{
  "data": {
    "customers": 1240,
    "purchaseEvent": "Order Completed",
    "currency": "USD",
    "scoredAt": "2026-10-02T14:05:00.000Z",
    "groups": {
      "champions": 96,
      "loyal": 210,
      "cant_lose_them": 38,
      "potential_loyalists": 174,
      "new_customers": 152,
      "need_attention": 120,
      "about_to_sleep": 108,
      "at_risk": 131,
      "hibernating": 117,
      "lost": 94
    }
  }
}
```