Get Retention
User retention cohorts by signup week.
Authorizations
Workspace API key (e.g. formo_xxx). Create one in the Formo dashboard under Team Settings > API.
Query Parameters
Inclusive start date (YYYY-MM-DD). Defaults to 7 days before date_to.
Inclusive end date (YYYY-MM-DD). Defaults to today.
Array of filter conditions, JSON-encoded in the query string. Entries use { field, op, value } and are combined with implicit AND. For example, filter traffic referred by Google with [{"field":"referrer","op":"contains","value":"google"}], or filter a page with [{"field":"page","op":"eq","value":"/pricing"}]. For in / nin, pass a non-empty array value such as ["chrome","firefox"] or a pipe-delimited string such as "chrome|firefox". Array string members cannot contain a literal |, which is reserved as the Tinybird membership separator. Optional one-level nested filters use the same canonical envelope and membership rule. On the user-aggregate endpoints (lifecycle, frequency) the same array also carries profile-family entries: profile metrics (net_worth_usd, volume, revenue, points), social identity fields, a lifecycle entry ({"field":"lifecycle","op":"in","value":"New|Power user"}), and resource entries using the stable fields chains.balance, apps.balance, tokens.balance, and labels.value with named qualifier properties (chain_id, app_id, token_address, scope, tag_id). The retired per-family parameters (socials, chain_filters, app_filters, token_filters, label_filters, profile_filters, lifecycle_filter) are rejected.
User identifier to cohort by. address (default) groups by wallet; anonymous_id groups by anonymous session ID.
address, anonymous_id Restrict the cohort-defining event to a single type (e.g. page, connect, track, transaction).
Restrict the cohort-defining event to a custom event name. Combine with event_type=track.
Minimum cohort size to include (default 10). Ignored when user_filters is set; all weeks are returned regardless of size.
x >= 0Number of weekly cohorts to return (default 12). Also drives the default date range when date_from/date_to are omitted.
1 <= x <= 52JSON array filtering users by profile attributes (device, browser, os, location, volume, revenue, utm_source, utm_medium, utm_campaign, utm_term, utm_content). When set, all weekly cohorts are returned regardless of min_users.
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.