Retrieve the RFM summaryMenu

Retrieve the RFM summary

GET/v1/reports/rfm

Requires an API key with the reports:read scope. About keys and scopes

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-Workspacestringoptional

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.

pattern ^[A-Za-z0-9._:-]{1,128}$

Returns

Returns 200 OK with a RfmSummary in data. Otherwise returns an error; Errors lists every code and which to retry.

customersinteger | nullrequired

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.

min 0

purchaseEventstring | nullrequired

The purchase event the last scoring counted (the workspace's purchaseEvent then); null until first scored.

currencystring | nullrequired

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.

scoredAtstring | nullrequired

When the groups were last scored (once a day); null until first.

date-time

groupsmap<string, integer> | nullrequired

How many customers each group holds, every group listed (an empty one as 0); null until first scored.

keys: one of champions, loyal, cant_lose_them, potential_loyalists, new_customers, need_attention, about_to_sleep, at_risk, hibernating, lost · values: min 0

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

const response = await fetch('https://api.kirora.io/v1/reports/rfm', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/reports/rfm",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/reports/rfm", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.kirora.io/v1/reports/rfm");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 200

{
  "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
    }
  }
}