> ## Documentation Index > Fetch the complete documentation index at: https://docs.formo.so/llms.txt > Use this file to discover all available pages before exploring further. # Get Retention > User retention cohorts by signup week. Returns the retention cohort table the dashboard renders on the Retention page. Each row is a cohort; columns are subsequent activity buckets. ## OpenAPI ````yaml GET /v0/retention openapi: 3.1.0 info: title: Formo Public API description: >- REST API for managing Formo projects, analytics, alerts, boards, charts, contracts, segments, and AI chat. **Auth.** Every endpoint on `api.formo.so` requires a workspace API key with the appropriate scopes (see `x-api-scopes`). The one exception is `POST /v0/raw_events`, which runs on `events.formo.so` and authenticates with the project SDK write key instead. **Response shape.** Successful responses return the resource directly (or `{ data: [...], total, page, size, has_more }` for paginated lists). HTTP status carries success/failure; there is no envelope wrapping success bodies. **Errors.** Non-2xx responses from `api.formo.so` use the `Error` envelope, with two exceptions: some rate-limit rejections reply in plain text, and `POST /v0/raw_events` returns a plain `{ "error": "..." }` object. Treat the HTTP status as authoritative and parse defensively: `{ error: { code, message, doc_url, param?, details? } }`. Branch on the machine-readable `code` (see `ErrorCode` enum) and follow `doc_url` to the matching section of the [errors reference](https://docs.formo.so/api/errors). **Idempotency.** Pass an `Idempotency-Key` header on write requests to alerts, boards, charts, contracts, segments, and import to make retries safe; the response is cached for 24 h and replayed on duplicate keys. Profile writes and `POST /v0/query` do not support it. version: 0.1.0 contact: name: Formo url: https://formo.so servers: - url: https://api.formo.so description: API Server (boards, alerts, contracts, segments, profiles, query, import) - url: https://events.formo.so description: Events Server (event ingestion) security: - WorkspaceApiKey: [] tags: - name: Alerts description: Manage project alerts and notifications - name: Boards description: Manage dashboard boards - name: Charts description: Manage charts within boards - name: Contracts description: Manage blockchain contract monitoring - name: Segments description: Manage user segments - name: Profiles description: Wallet profiles and import - name: Query description: >- Execute SQL queries and call pre-built analytics endpoints (KPIs, top pages, lifecycle, retention, revenue). Requires the query:read scope. - name: Events description: Event ingestion API (events.formo.so) paths: /v0/retention: get: tags: - Query summary: Get user retention cohorts operationId: getAnalyticsRetention parameters: - $ref: '#/components/parameters/AnalyticsDateFrom' - $ref: '#/components/parameters/AnalyticsDateTo' - $ref: '#/components/parameters/AnalyticsFilters' - name: id_type in: query schema: type: string enum: - address - anonymous_id default: address description: >- User identifier to cohort by. `address` (default) groups by wallet; `anonymous_id` groups by anonymous session ID. - name: event_type in: query schema: type: string description: >- Restrict the cohort-defining event to a single type (e.g. `page`, `connect`, `track`, `transaction`). example: track - name: event_name in: query schema: type: string description: >- Restrict the cohort-defining event to a custom event name. Combine with `event_type=track`. example: swap - name: min_users in: query schema: type: integer default: 10 minimum: 0 description: >- Minimum cohort size to include (default 10). Ignored when `user_filters` is set; all weeks are returned regardless of size. - name: limit in: query schema: type: integer default: 12 minimum: 1 maximum: 52 description: >- Number of weekly cohorts to return (default 12). Also drives the default date range when `date_from`/`date_to` are omitted. - name: user_filters in: query description: >- JSON 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`. schema: type: string example: '[{"field":"device","op":"eq","value":"desktop"}]' responses: '200': description: Retention cohorts content: application/json: schema: $ref: '#/components/schemas/AnalyticsResponse' example: 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 '401': description: Invalid API key content: application/json: schema: $ref: '#/components/schemas/RestApiError' '403': description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/RestApiError' components: parameters: AnalyticsDateFrom: name: date_from in: query schema: type: string format: date description: Inclusive start date (YYYY-MM-DD). Defaults to 7 days before date_to. AnalyticsDateTo: name: date_to in: query schema: type: string format: date description: Inclusive end date (YYYY-MM-DD). Defaults to today. AnalyticsFilters: name: filters in: query description: >- 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. Overview also accepts raw Data source filters with `field` set to `channel`, ops `eq`/`neq`/`in`/`nin`, and values `web`, `mobile`, `api`, `import`, `server`, `onchain`; this is distinct from acquisition Channel (`channel_type`) and the two can be combined. schema: type: string example: '[{"field":"referrer","op":"contains","value":"google"}]' schemas: AnalyticsResponse: type: object description: >- 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. properties: data: type: array items: type: object additionalProperties: true meta: type: array items: type: object properties: name: type: string type: type: string rows: type: integer rows_before_limit_at_least: type: integer statistics: type: object additionalProperties: true RestApiError: $ref: '#/components/schemas/Error' description: >- Deprecated alias for `Error`. Existing endpoint specs reference this name; new specs should reference `Error` directly. Error: type: object description: >- Standard error envelope returned by every public API endpoint for any non-2xx response. The HTTP status code carries success/failure; the body provides a machine-readable `code`, a human-readable `message`, and a `doc_url` pointing at the matching section of the docs so agents can fetch context on the fly. properties: error: type: object required: - code - message - doc_url properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Human-readable error description. Wording may change between releases, so branch on `code`, not `message`. doc_url: type: string format: uri description: >- Link to the matching section of the errors reference at https://docs.formo.so/api/errors. param: type: string description: >- When the error pertains to a specific request field, the dotted path to that field (e.g. `body.trigger_filters.0.value`). details: type: object additionalProperties: true description: >- Code-specific extra context. For `INVALID_VALIDATION_REQUEST` this is a `{ fieldPath: message }` map of every Zod validation failure. required: - error ErrorCode: type: string description: >- Stable, enumerated error codes. New codes may be added in any release; clients should treat unknown codes as the closest matching HTTP status family. enum: - INTERNAL_SERVER_ERROR - INVALID_VALIDATION_REQUEST - UNAUTHORIZED - BAD_REQUEST - FORBIDDEN - NOT_FOUND - CONFLICT - INVALID_CHAIN_ID - CONTEXT_LIMIT_EXCEEDED - SERVICE_UNAVAILABLE - TOO_MANY_REQUESTS - IDEMPOTENCY_IN_PROGRESS - INVALID_IDEMPOTENCY_KEY securitySchemes: WorkspaceApiKey: type: http scheme: bearer description: >- Workspace API key (e.g. `formo_xxx`). Create one in the Formo dashboard under Team Settings > API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.