Skip to main content
GET
Get user retention cohorts
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.

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