Rybbit
Insights

Get Retention

Returns cohort-based retention analysis data. Users are grouped into cohorts based on their first visit, and retention is tracked over subsequent time periods.

GET /api/sites/:site/retention

Returns cohort-based retention analysis data. Users are grouped into cohorts based on their first visit, and retention is tracked over subsequent time periods.

Path Parameters

Prop

Type

Query Parameters

Prop

Type

Response

Prop

Type

RetentionData Object

Prop

Type

CohortData Object

Prop

Type

Request
curl -X GET "https://app.rybbit.io/api/sites/1/retention?mode=week&range=90" \
  -H "Authorization: Bearer your_api_key_here"
Request
const response = await fetch(
  'https://app.rybbit.io/api/sites/1/retention?mode=week&range=90',
  {
    headers: {
      'Authorization': 'Bearer your_api_key_here'
    }
  }
);

const data = await response.json();
Request
import requests

response = requests.get(
    'https://app.rybbit.io/api/sites/1/retention23',
    params={
        'mode': 'week',
        'range': 90
    },
    headers={
        'Authorization': 'Bearer your_api_key_here'
    }
)

data = response.json()
Request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/retention?mode=week&range=90');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer your_api_key_here'
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
Request
require 'net/http'
require 'json'

uri = URI('https://app.rybbit.io/api/sites/1/retention?mode=week&range=90')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer your_api_key_here'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
Request
req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/retention?mode=week&range=90", nil)
req.Header.Set("Authorization", "Bearer your_api_key_here")

client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

var data map[string]interface{}
json.NewDecoder(resp.Body).Decode(&data)
Request
let client = reqwest::Client::new();
let res = client
    .get("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90")
    .header("Authorization", "Bearer your_api_key_here")
    .send()
    .await?;

let data: serde_json::Value = res.json().await?;
Request
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90"))
    .header("Authorization", "Bearer your_api_key_here")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
Request
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90");
var data = await response.Content.ReadAsStringAsync();
Response
{
  "data": {
    "cohorts": {
      "2024-01-01": {
        "size": 1250,
        "percentages": [100, 45.2, 32.1, 28.5, 25.3, 22.1]
      },
      "2024-01-08": {
        "size": 1420,
        "percentages": [100, 48.5, 35.2, 30.1, 26.8, null]
      },
      "2024-01-15": {
        "size": 1380,
        "percentages": [100, 46.8, 33.5, 29.2, null, null]
      },
      "2024-01-22": {
        "size": 1510,
        "percentages": [100, 44.2, 31.8, null, null, null]
      },
      "2024-01-29": {
        "size": 1290,
        "percentages": [100, 47.1, null, null, null, null]
      }
    },
    "maxPeriods": 5,
    "mode": "week",
    "range": 90
  }
}

Understanding Retention Data

The retention data shows how many users from each cohort return in subsequent periods:

  • Period 0: Always 100% (the cohort's first visit)
  • Period 1: Users who returned 1 week later
  • Period 2: Users who returned 2 weeks later
  • etc.

A null value indicates that period hasn't occurred yet for that cohort.

Visualization Example

Building a Retention Table
const { cohorts, maxPeriods } = data.data;

// Headers: Cohort, Size, Week 0, Week 1, Week 2, ...
const headers = ['Cohort', 'Size',
  ...Array(maxPeriods + 1).fill(0).map((_, i) => `Week ${i}`)
];

// Rows
Object.entries(cohorts).forEach(([date, cohort]) => {
  const row = [
    date,
    cohort.size,
    ...cohort.percentages.map(p => p !== null ? `${p}%` : '-')
  ];
  console.log(row.join(' | '));
});