> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manalens.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get User Frequency

> Read how many visitors had one, two, three or more sessions in the date range.

Returns the visitors grouped by their number of sessions in the range. Use it to see how many players come back more than once. See [audience insights](https://docs.manalens.dev/features/audience-insights.md).


## OpenAPI

````yaml GET /v0/projects/{projectId}/query/user-frequency
openapi: 3.1.0
info:
  title: Manalens API
  version: 0.1.0
  description: >-
    The public API of Manalens: event ingestion, profile properties and the
    Query API. Success bodies are the resource, with no envelope. Errors use the
    `Error` format. See https://docs.manalens.dev/api/overview.
servers:
  - url: https://api.manalens.dev
    description: API
  - url: https://events.manalens.dev
    description: Event ingestion
security: []
tags:
  - name: Events
    description: Send website, game and server events
  - name: Profiles
    description: Set and delete profile properties
  - name: Query
    description: Read analytics reports with an API key
paths:
  /v0/projects/{projectId}/query/user-frequency:
    get:
      tags:
        - Query
      summary: Get user frequency
      description: How many visitors had 1, 2, 3 or more sessions in the date range.
      operationId: getUserFrequency
      parameters:
        - name: projectId
          in: path
          required: true
          description: The project ID
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/date_from'
        - $ref: '#/components/parameters/date_to'
        - $ref: '#/components/parameters/page_path'
        - $ref: '#/components/parameters/utm_source'
        - $ref: '#/components/parameters/utm_medium'
        - $ref: '#/components/parameters/utm_campaign'
        - $ref: '#/components/parameters/utm_content'
        - $ref: '#/components/parameters/utm_term'
        - $ref: '#/components/parameters/ref'
        - $ref: '#/components/parameters/paid_source'
        - $ref: '#/components/parameters/click_id'
        - $ref: '#/components/parameters/channel_type'
        - $ref: '#/components/parameters/referrer'
        - $ref: '#/components/parameters/locale'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/os'
        - $ref: '#/components/parameters/browser'
        - $ref: '#/components/parameters/country'
        - $ref: '#/components/parameters/currency'
        - $ref: '#/components/parameters/currency_mode'
        - $ref: '#/components/parameters/filters'
      responses:
        '200':
          description: The report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportRows'
        '400':
          description: >-
            `INVALID_QUERY`: a parameter or the body is not valid. The message
            names the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            `UNAUTHORIZED`: the API key is missing, malformed, unknown or
            revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: >-
            `SUBSCRIPTION_REQUIRED`: the workspace has no active subscription or
            trial. `PLAN_UPGRADE_REQUIRED`: API keys need the Scale plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            `FORBIDDEN`: the key does not have the scope, its creator left the
            workspace, or the request came from a browser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            `NOT_FOUND`: the key belongs to another project, or the resource
            does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`TOO_MANY_REQUESTS`: the key or workspace budget is used up'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds to wait before a retry
              schema:
                type: integer
        '500':
          description: '`INTERNAL`: an unexpected error. The body has a `request_id`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKey: []
components:
  parameters:
    date_from:
      name: date_from
      in: query
      required: false
      description: 'First day (UTC) as YYYY-MM-DD. Default: 29 days before date_to.'
      schema:
        type: string
        pattern: ^\d{4}-\d{2}-\d{2}$
    date_to:
      name: date_to
      in: query
      required: false
      description: >-
        Last day (UTC) as YYYY-MM-DD. Default: today. The range is at most 367
        days.
      schema:
        type: string
        pattern: ^\d{4}-\d{2}-\d{2}$
    page_path:
      name: page_path
      in: query
      required: false
      description: Only events on this page path
      schema:
        type: string
        maxLength: 2048
        pattern: ^\/
    utm_source:
      name: utm_source
      in: query
      required: false
      schema:
        type: string
        maxLength: 255
    utm_medium:
      name: utm_medium
      in: query
      required: false
      schema:
        type: string
        maxLength: 255
    utm_campaign:
      name: utm_campaign
      in: query
      required: false
      schema:
        type: string
        maxLength: 255
    utm_content:
      name: utm_content
      in: query
      required: false
      schema:
        type: string
        maxLength: 255
    utm_term:
      name: utm_term
      in: query
      required: false
      schema:
        type: string
        maxLength: 255
    ref:
      name: ref
      in: query
      required: false
      description: Referral code (`ref` link parameter)
      schema:
        type: string
        maxLength: 255
    paid_source:
      name: paid_source
      in: query
      required: false
      description: Ad network of a paid click
      schema:
        type: string
        enum:
          - google
          - meta
          - microsoft
          - tiktok
          - twitter
          - linkedin
          - reddit
          - snapchat
          - paid_utm
    click_id:
      name: click_id
      in: query
      required: false
      description: Ad click ID (gclid, fbclid and others)
      schema:
        type: string
        maxLength: 255
    channel_type:
      name: channel_type
      in: query
      required: false
      description: Acquisition channel
      schema:
        type: string
        enum:
          - Paid Search
          - Paid Video
          - Paid Social
          - Paid Other
          - Email
          - Referrals
          - Display
          - AI
          - Organic Search
          - Organic Social
          - Organic Video
          - Referrers
          - Direct
    referrer:
      name: referrer
      in: query
      required: false
      description: Referrer origin, for example https://www.reddit.com
      schema:
        type: string
        maxLength: 2048
    locale:
      name: locale
      in: query
      required: false
      schema:
        type: string
        maxLength: 32
    device:
      name: device
      in: query
      required: false
      schema:
        type: string
        enum:
          - desktop
          - mobile
          - tablet
          - bot
    os:
      name: os
      in: query
      required: false
      schema:
        type: string
        enum:
          - windows
          - macos
          - ios
          - android
          - linux
          - other
    browser:
      name: browser
      in: query
      required: false
      schema:
        type: string
        enum:
          - chrome
          - safari
          - firefox
          - edge
          - opera
          - other
    country:
      name: country
      in: query
      required: false
      description: ISO 3166-1 alpha-2 country code
      schema:
        type: string
        pattern: ^[A-Za-z]{2}$
    currency:
      name: currency
      in: query
      required: false
      description: 'Report currency for revenue (ISO 4217). Default: USD.'
      schema:
        type: string
        pattern: ^[A-Z]{3}$
    currency_mode:
      name: currency_mode
      in: query
      required: false
      description: >-
        `convert` (default) converts other currencies with the rate of the event
        day. `only` counts the report currency alone.
      schema:
        type: string
        enum:
          - convert
          - only
    filters:
      name: filters
      in: query
      required: false
      description: >-
        Operator filters as a JSON array of `{ "field", "op", "value" }`,
        combined with AND. At most 20.
      schema:
        type: string
        maxLength: 8192
  schemas:
    ReportRows:
      type: object
      properties:
        date_from:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: First day of the report
        date_to:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Last day of the report
        rows:
          type: array
          items:
            type: object
            propertyNames:
              type: string
            additionalProperties: {}
      required:
        - date_from
        - date_to
        - rows
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable, machine-readable code. Branch on it.
            message:
              type: string
              description: A human-readable text. The wording can change.
            request_id:
              description: 'INTERNAL only: quote it when you contact support'
              type: string
          required:
            - code
            - message
      required:
        - error
      description: >-
        The error format of every endpoint. See
        https://docs.manalens.dev/api/errors.
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: >-
        An API key (`mana_api_...`) with scopes. It reads reports and writes
        profile properties.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.