Skip to main content
GET
/
v0
/
retention
Get user retention cohorts
curl --request GET \
  --url https://api.formo.so/v0/retention \
  --header 'Authorization: Bearer <token>'
{
  "meta": [
    {
      "name": "metric",
      "type": "Tuple(project_id String, user_count UInt64, day7_retained UInt64, day30_retained UInt64, day90_retained UInt64, day7_retention_rate Float64, day30_retention_rate Float64, day90_retention_rate Float64)"
    },
    {
      "name": "user",
      "type": "Array(Tuple(project_id String, cohort_week Date, num_users UInt64, week_0 Float64, week_1 Float64, week_2 Float64, week_3 Float64, week_4 Float64, week_5 Float64, week_6 Float64, week_7 Float64, week_8 Float64, week_9 Float64, week_10 Float64, week_11 Float64, week_12 Float64))"
    }
  ],
  "data": [
    {
      "metric": [
        "proj_abc",
        1284,
        412,
        198,
        76,
        0.32,
        0.154,
        0.059
      ],
      "user": [
        [
          "proj_abc",
          "2025-07-28",
          142,
          100,
          48,
          32,
          22,
          18,
          14,
          12,
          11,
          9,
          8,
          7,
          6,
          null,
          null
        ],
        [
          "proj_abc",
          "2025-08-04",
          178,
          100,
          52,
          36,
          26,
          20,
          16,
          14,
          12,
          10,
          9,
          8,
          null,
          null,
          null
        ],
        [
          "proj_abc",
          "2025-08-11",
          165,
          100,
          50,
          34,
          24,
          19,
          15,
          13,
          11,
          null,
          null,
          null,
          null,
          null,
          null
        ]
      ]
    }
  ],
  "rows": 1,
  "rows_before_limit_at_least": 1
}
Returns the retention cohort table the dashboard renders on the Retention page. Each row is a cohort; columns are subsequent activity buckets.

Authorizations

​
Authorization
string
header
required

Workspace API key (e.g. formo_xxx). Create one in the Formo dashboard under Team Settings > API Keys.

Query Parameters

​
date_from
string<date>

Inclusive start date (YYYY-MM-DD). Defaults to 7 days before date_to.

​
date_to
string<date>

Inclusive end date (YYYY-MM-DD). Defaults to today.

​
id_type
enum<string>
default:address

User identifier to cohort by. address (default) groups by wallet; anonymous_id groups by anonymous session ID.

Available options:
address,
anonymous_id
​
event_type
string

Restrict the cohort-defining event to a single type (e.g. page, connect, track, transaction).

​
event_name
string

Restrict the cohort-defining event to a custom event name. Combine with event_type=track.

​
min_users
integer
default:10

Minimum cohort size to include (default 10). Ignored when user_filters is set; all weeks are returned regardless of size.

Required range: x >= 0
​
limit
integer
default:12

Number of weekly cohorts to return (default 12). Also drives the default date range when date_from/date_to are omitted.

Required range: 1 <= x <= 52

Response

Retention cohorts

Analytics endpoint response. The data array contains the rows; the exact row shape depends on the endpoint. meta carries column type information for rendering, rows is the row count, and statistics holds query timing metadata.

​
data
object[]
​
meta
object[]
​
rows
integer
​
rows_before_limit_at_least
integer
​
statistics
object