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

# Get cohort analytics data

> Returns cohort-over-time tables for the project. A cohort is a group of users
sharing an acquisition event (see `cohort_definition`). Rows are cohorts,
columns are time offsets (see `grouping`). Cells are the `metric` (revenue,
subscriptions, payers, ARPU, ARPPU).

Use `GET /v4/analytics/cohorts/meta` to discover valid filter attributes and
their concrete values for the project.




## OpenAPI

````yaml /api-reference/rest-api-v4.yaml get /analytics/cohorts
openapi: 3.0.3
info:
  title: Qonversion REST API v4
  version: '4.0'
  description: >-
    Qonversion REST API v4 follows REST standards. It has predictable
    resource-oriented URLs, accepts JSON-encoded request bodies, returns
    JSON-encoded responses, and uses standard HTTP response codes,
    authentication, and verbs.
servers:
  - url: https://api.qonversion.io/v4
    description: Production
security:
  - secretAuth: []
tags:
  - name: Users
    description: Retrieve Qonversion users
  - name: User Properties
    description: Manage user-level attributes
  - name: Identities
    description: Link Qonversion users to your own auth IDs
  - name: Entitlements
    description: Entitlement definitions and user grants
  - name: Purchases
    description: A user's purchase history
  - name: Products
    description: Products configured in the Qonversion dashboard
  - name: Customers
    description: Aggregated customer records, properties, permissions, and metrics
  - name: Segments
    description: Dynamic and system segments of users
  - name: Experiments
    description: Paywall and offering A/B experiments
  - name: Screens
    description: No-code paywall screens — CRUD, publish, analytics
  - name: Analytics
    description: Charts, cards, cohorts, LTV, and insights
  - name: Exports
    description: Asynchronous data exports
  - name: Events
    description: Event catalog
  - name: Scheduled Reports
    description: Recurring reports delivered to external destinations
  - name: Integrations
    description: Third-party integrations configuration
  - name: Automations
    description: Event-driven automations
  - name: Project Settings
    description: Project-level configuration, secret, and store credentials
paths:
  /analytics/cohorts:
    get:
      tags:
        - Analytics
      summary: Get cohort analytics data
      description: >
        Returns cohort-over-time tables for the project. A cohort is a group of
        users

        sharing an acquisition event (see `cohort_definition`). Rows are
        cohorts,

        columns are time offsets (see `grouping`). Cells are the `metric`
        (revenue,

        subscriptions, payers, ARPU, ARPPU).


        Use `GET /v4/analytics/cohorts/meta` to discover valid filter attributes
        and

        their concrete values for the project.
      operationId: v4GetAnalyticsCohorts
      parameters:
        - name: cohort_from
          in: query
          required: false
          description: >-
            Cohort-range start (Unix timestamp, seconds). Defaults to `now - 90
            days`.
          schema:
            type: integer
            format: int64
        - name: cohort_to
          in: query
          required: false
          description: >-
            Cohort-range end (Unix timestamp, seconds). Defaults to the current
            time. Normalised to the next day's 00:00 UTC on the server.
          schema:
            type: integer
            format: int64
        - name: mode
          in: query
          required: false
          description: >
            * `by_renewals` — columns are subscription renewal indexes (P1, P2,
            …).

            * `by_days` — columns are calendar offsets from the cohort start.
          schema:
            type: string
            enum:
              - by_renewals
              - by_days
            default: by_renewals
        - name: grouping
          in: query
          required: false
          description: Column (period) granularity.
          schema:
            type: string
            enum:
              - day
              - week
              - month
              - quarter
              - year
            default: week
        - name: environment
          in: query
          required: false
          description: 'Environment: `0` = sandbox, `1` = production.'
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 1
        - name: cohort_definition
          in: query
          required: false
          description: |
            What event defines cohort membership.
              * `new_customers` — first app install / user creation.
              * `initial_conversions` — first trial or paid conversion.
              * `new_paying` — first paid transaction.
          schema:
            type: string
            enum:
              - new_customers
              - initial_conversions
              - new_paying
            default: new_customers
        - name: revenue_type
          in: query
          required: false
          description: |
            * `gross` — raw transaction values.
            * `net` — after refunds and store commission.
          schema:
            type: string
            enum:
              - gross
              - net
            default: gross
        - name: currency
          in: query
          required: false
          description: >-
            ISO 4217 currency code for monetary cells. Non-USD values are
            converted at the transaction's historical rate.
          schema:
            type: string
            pattern: ^[A-Z]{3}$
            default: USD
        - name: group_by
          in: query
          required: false
          description: >
            Optional segmentation attribute — when set, response includes a
            `segments` array,

            one entry per attribute value. Allowed values match
            `filter_conditions[].attribute`

            from cohorts/meta.
          schema:
            type: string
          example: target_platform
        - name: filter[<attribute>][]
          in: query
          required: false
          description: Same attribute-scoped filter schema as the charts endpoint.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        '200':
          description: Cohort table.
          headers:
            Cache-Control:
              schema:
                type: string
                example: no-cache
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4AnalyticsCohorts'
              example:
                object: analytics_cohorts
                url: /v4/analytics/cohorts
                mode: by_renewals
                grouping: week
                cohort_from: 1768780800
                cohort_to: 1776816000
                currency: USD
                period_labels:
                  - P1
                  - P2
                  - P3
                  - P4
                  - P5
                  - P6
                  - P7
                  - P8
                  - P9
                  - P10
                  - P11
                  - P12
                cohorts: []
                total: null
                max_values:
                  arpas: 0
                  arppu: 0
                  arpu: 0
                  payers: 0
                  revenue: 0
                  subscriptions: 0
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4Error'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4Error'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4Error'
        '502':
          description: Upstream service failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4Error'
        '504':
          description: Upstream timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4Error'
      security:
        - secretAuth: []
components:
  schemas:
    V4AnalyticsCohorts:
      type: object
      required:
        - object
        - url
        - mode
        - grouping
        - cohort_from
        - cohort_to
        - currency
        - period_labels
        - cohorts
        - max_values
      properties:
        object:
          type: string
          enum:
            - analytics_cohorts
        url:
          type: string
        mode:
          type: string
          enum:
            - by_renewals
            - by_days
        grouping:
          type: string
          enum:
            - day
            - week
            - month
            - quarter
            - year
        cohort_from:
          type: integer
          format: int64
        cohort_to:
          type: integer
          format: int64
        currency:
          type: string
        period_labels:
          type: array
          description: >-
            Column labels — `P1`, `P2`, … for `by_renewals`, date strings for
            `by_days`.
          items:
            type: string
        cohorts:
          type: array
          description: >-
            One row per cohort window. Empty when the project has no qualifying
            cohorts in the range.
          items:
            type: object
            additionalProperties: true
        total:
          type: object
          nullable: true
          additionalProperties: true
          description: Aggregated totals row. Null when the table is empty.
        max_values:
          type: object
          description: >-
            Maximum per-metric value across the table — used for heatmap
            coloring in the UI.
          additionalProperties:
            type: number
        group_by:
          type: string
          description: Present only when `group_by` was supplied on the request.
        segments:
          type: array
          description: >-
            Present only when `group_by` was supplied. One entry per
            segmentation value.
          items:
            type: object
            additionalProperties: true
    V4Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
          properties:
            type:
              type: string
              enum:
                - request
                - resource
                - logical
                - internal
            code:
              type: string
              description: |
                Machine-readable snake_case error code. Examples include
                `invalid_data`, `invalid_request`, `invalid_product_id`,
                `not_found`, `already_exists`, `offering_already_exists`,
                `product_not_in_project`, `cannot_set_main_directly`,
                `cannot_demote_main`, `cannot_patch_experiment_variant`,
                `cannot_delete_experiment_variant`, and
                `cannot_setmain_experiment_variant`. Resource-specific codes
                are documented on the corresponding reference page.
            message:
              type: string
              description: Human-readable description. May change; do not parse.
            details:
              type: array
              nullable: true
              description: Per-field validation errors, present on 400 validation failures.
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
  securitySchemes:
    secretAuth:
      type: http
      scheme: bearer
      bearerFormat: sk_…
      description: >-
        Bearer authentication using the project **Secret Key** (prefixed with
        `sk_`, or `test_sk_` for sandbox). All v4 public endpoints require the
        Secret Key — see [Authentication](/reference/v4/authentication). Never
        expose the Secret Key in client-side code.

````