> ## 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 User Frequency > Distribution of users by visit count over the selected window. Returns how many users visited 1, 2, 3+ times in the selected window - the data behind the dashboard's frequency histogram. ## OpenAPI ````yaml GET /v0/frequency 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.** All endpoints require a workspace API key with the appropriate scopes (see `x-api-scopes`). **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.** Every non-2xx response uses the `Error` envelope: `{ 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 POST/PUT/PATCH/DELETE to make retries safe; the response is cached for 24 h and replayed on duplicate keys. 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/frequency: get: tags: - Query summary: Get visit-frequency distribution operationId: getAnalyticsFrequency parameters: - $ref: '#/components/parameters/AnalyticsDateFrom' - $ref: '#/components/parameters/AnalyticsDateTo' - $ref: '#/components/parameters/AnalyticsFilters' - $ref: '#/components/parameters/AnalyticsLifecycleFilter' - $ref: '#/components/parameters/AnalyticsIncludePreviousPeriod' - $ref: '#/components/parameters/AnalyticsProfileFilters' - $ref: '#/components/parameters/AnalyticsSocials' - $ref: '#/components/parameters/AnalyticsAppFilters' - $ref: '#/components/parameters/AnalyticsTokenFilters' - $ref: '#/components/parameters/AnalyticsChainFilters' - $ref: '#/components/parameters/AnalyticsBehaviorFilters' - $ref: '#/components/parameters/AnalyticsChannelFilter' - $ref: '#/components/parameters/AnalyticsLabelFilters' responses: '200': description: Visit frequency distribution content: application/json: schema: $ref: '#/components/schemas/AnalyticsResponse' example: meta: - name: project_id type: String - name: session_bucket type: String - name: user_count type: UInt64 - name: avg_session_per_user type: Float64 data: - project_id: proj_abc session_bucket: 1 session user_count: 412 avg_session_per_user: 1 - project_id: proj_abc session_bucket: 2 - 10 sessions user_count: 287 avg_session_per_user: 4.6 - project_id: proj_abc session_bucket: 10 - 30 sessions user_count: 76 avg_session_per_user: 16.2 - project_id: proj_abc session_bucket: 30 - 50 sessions user_count: 18 avg_session_per_user: 38.4 - project_id: proj_abc session_bucket: '> 50 sessions' user_count: 5 avg_session_per_user: 84 rows: 5 rows_before_limit_at_least: 5 '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. Each entry is `{ field, op, value }`. Use `in` / `notIn` with a pipe-delimited `value` (e.g. `"chrome|firefox"`) for multi-value matching. content: application/json: schema: type: array items: $ref: '#/components/schemas/AnalyticsFilterCondition' example: - field: location op: equals value: US - field: device op: in value: desktop|mobile AnalyticsLifecycleFilter: name: lifecycle_filter in: query schema: type: string enum: - New - Returning - Power user - Resurrected - At Risk - Churned description: Restrict results to a single lifecycle stage. AnalyticsIncludePreviousPeriod: name: include_previous_period in: query schema: type: boolean description: >- When `true`, returns both current and previous period metrics for week-over-week comparison. The previous period is non-overlapping and equal in length to the current range. AnalyticsProfileFilters: name: profile_filters in: query description: >- JSON array filtering by wallet profile attributes (e.g. net worth, total tx count). Each entry is `{ field, op, value }`. content: application/json: schema: type: array items: $ref: '#/components/schemas/AnalyticsFilterCondition' example: - field: net_worth_usd op: greater value: '1000' AnalyticsSocials: name: socials in: query description: >- JSON array of social platforms to filter users by. Users must have at least one of the listed identities (e.g. `ens`, `farcaster`, `lens`, `twitter`). content: application/json: schema: type: array items: type: string example: - ens - farcaster AnalyticsAppFilters: name: app_filters in: query description: >- JSON array of arrays describing DeFi app usage filters. Each entry is `[scope, chain_id, app_id, op, value]` where `scope` is `protocol` or `any`. content: application/json: schema: type: array items: type: array example: - - protocol - 1 - uniswap-v3 - greater - '0' AnalyticsTokenFilters: name: token_filters in: query description: >- JSON array of arrays describing token-holding filters. Each entry is `[scope, chain_id, app_id, token_address, op, value]` where `scope` is `protocol` or `any`. content: application/json: schema: type: array items: type: array example: - - any - 1 - '' - '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' - greater - '100' AnalyticsChainFilters: name: chain_filters in: query description: >- JSON array of arrays describing chain-activity filters. Each entry is `[chain_id, op, value]`. content: application/json: schema: type: array items: type: array example: - - 1 - greater - '0' AnalyticsBehaviorFilters: name: behavior_filters in: query description: >- JSON array filtering users by event-based behavior with counts and either an absolute date range or a window relative to the user's first event. Each entry is `{ event, op, count, date_from?, date_to?, event_type?, relative_to?, window? }`. When `relative_to: "first_seen"` is set, the matching events must occur within `window.value` `window.unit` (`hour` | `day`) after the user's first event; `date_from`/`date_to` are ignored. `event_type` narrows matching to a specific event-type column (`page`, `connect`, `disconnect`, `chain`, `signature`, `transaction`, `track`, `decoded_log`, `detect`, `identify`); for `track` and `decoded_log` the `event` field is the named identifier; for other types only the `type` column is matched. content: application/json: schema: type: array items: type: object example: - event: swap event_type: track op: greaterOrEqual count: 1 relative_to: first_seen window: value: 24 unit: hour AnalyticsChannelFilter: name: channel_filter in: query description: >- JSON object filtering users by acquisition channel. Format: `{ op, value }` where `op` is one of `equals`, `notEquals`, `in`, `notIn` and `value` is one of `import`, `api`, `web`, `mobile` (pipe-delimited for `in`/`notIn`). content: application/json: schema: type: object example: op: in value: web|mobile AnalyticsLabelFilters: name: label_filters in: query description: >- JSON array of arrays for filtering users by wallet labels. Each entry is `[tag_id, chain_id, op, value]`. content: application/json: schema: type: array items: type: array example: - - whale - 1 - equals - 'true' 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. AnalyticsFilterCondition: type: object description: >- A single analytics filter condition. Use `in` / `notIn` with a pipe-delimited string value (e.g. `"a|b|c"`) for multi-value matches. properties: field: type: string description: >- Column to filter on. Standard session columns: `device`, `browser`, `os`, `location`, `referrer`, `ref`, `origin`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`. Track-event columns: `event`, `type`. Numeric event properties: `volume`, `revenue`, `points`. op: type: string enum: - equals - notEquals - greater - less - greaterOrEqual - lessOrEqual - in - notIn description: Comparison operator. value: oneOf: - type: string - type: number - type: boolean description: >- Value to compare against. For `in` / `notIn`, pass a pipe-delimited string (e.g. `"chrome|firefox"`). required: - field - op - value 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 Keys. ````