# Retrieve cohort data

> Retrieve cohort data to track user groups over time.
>
> Rate limit: 2 requests per second.

## OpenAPI

```yaml
/api-specs/export-analytics-api.yaml post /api/v1/client-api/metrics/cohort/
openapi: 3.1.0
info:
  title: Adapty Export Analytics API
  version: 1.0.0
  description: |
    The Adapty Export Analytics API allows you to export your analytics data to CSV or JSON format, 
    giving you the flexibility to dive deeper into your app's performance metrics, customize reports, 
    and analyze trends over time. With this API, you can easily pull detailed analytics data, 
    making it convenient to track, share, and refine your data insights as needed.
servers:
  - url: https://api-admin.adapty.io
    description: Production server
security:
  - apikeyAuth: []
paths:
  /api/v1/client-api/metrics/cohort/:
    post:
      summary: Retrieve cohort data
      description: |-
        Retrieve cohort data to track user groups over time.

        Rate limit: 2 requests per second.
      operationId: retrieveCohortData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CohortDataRequest"
            examples:
              basic:
                summary: Basic cohort data request
                value:
                  filters:
                    date:
                      - "2024-04-01"
                      - "2024-09-30"
                    store:
                      - app_store
                    country:
                      - us
                  period_unit: month
                  period_type: renewals
                  value_type: absolute
                  value_field: subscriptions
      responses:
        "200":
          description: Cohort data retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CohortDataResponse"
              example:
                data:
                  - segment_start_date: "2024-04-01"
                    type: total
                    title: Total
                    total_installs: 0
                    total_subscriptions: 0
                    total_paid_subscribers: 0
                    total_revenue_usd: 0
                    total_proceeds_usd: 0
                    total_net_revenue_usd: 0
                    total_anrpas_usd: 0
                    total_appas_usd: 0
                    total_arpas_usd: 0
                    total_anrppu_usd: 0
                    total_apppu_usd: 0
                    total_arppu_usd: 0
                    total_anrpu_usd: 0
                    total_appu_usd: 0
                    total_arpu_usd: 0
                    predict: null
                    values:
                      - arpas_usd: 0
                        appas_usd: 0
                        anrpas_usd: 0
                        anrppu_usd: 0
                        apppu_usd: 0
                        arppu_usd: 0
                        anrpu_usd: 0
                        appu_usd: 0
                        arpu_usd: 0
                        installs: 0
                        period: 1
                        revenue_usd: 0
                        proceeds_usd: 0
                        net_revenue_usd: 0
                        revenue_relative: 0
                        proceeds_relative: 0
                        net_revenue_relative: 0
                        subscriptions: 0
                        subscriptions_relative: 0
                        subscribers: 0
                        subscribers_relative: 0
                        currently_active_period: false
            text/csv:
              schema:
                type: string
                description: Cohort data in CSV format
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "429":
          description: Rate limit exceeded. Maximum 2 requests per second per API key.
components:
  schemas:
    CohortDataRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: "#/components/schemas/MetricsFilters"
        period_unit:
          type: string
          enum:
            - day
            - week
            - month
            - quarter
            - year
          description: Specify the time interval for aggregating analytics data
          default: month
        period_type:
          type: string
          enum:
            - renewals
            - days
          description: Analyze data by renewals or by days
          default: renewals
        value_type:
          type: string
          enum:
            - absolute
            - relative
          description: Specify how values are displayed
          default: absolute
        value_field:
          type: string
          enum:
            - revenue
            - arppu
            - arpu
            - arpas
            - subscribers
            - subscriptions
          description: Specify the type of values displayed
          default: revenue
        accounting_type:
          type: string
          enum:
            - revenue
            - proceeds
            - net_revenue
          description: The accounting method used
          default: revenue
        renewal_days:
          type: array
          items:
            type: integer
          description: List of days since the app was installed for the cohort type period_type=days
        prediction_months:
          type: integer
          enum:
            - 3
            - 6
            - 9
            - 12
            - 18
            - 24
          description: Enter how many months of prediction you want
          default: 12
        format:
          type: string
          enum:
            - json
            - csv
          description: Specify the export file format
          default: json
    CohortDataResponse:
      type: object
      description: Response containing cohort analysis data showing user behavior over time
      properties:
        data:
          type: array
          description: Array of cohort segments, each representing a group of users who started in the same period
          items:
            $ref: "#/components/schemas/CohortSegment"
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer
    UnauthorizedError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer
    MetricsFilters:
      type: object
      required:
        - date
      properties:
        date:
          type: array
          items:
            type: string
          description: Enter the date or time period for which you want to retrieve chart data
        compare_date:
          type: array
          items:
            type: string
          description: Enter the comparison date or time period
        store:
          type: array
          items:
            type: string
          description: Filter by the app store where the purchase was made
        country:
          type: array
          items:
            type: string
          description: Filter by the 2-letter country code where the purchase took place
        store_product_id:
          type: array
          items:
            type: string
          description: Unique identifier of a product from the app store
        duration:
          type: array
          items:
            type: string
          description: Specify the subscription duration
        attribution_source:
          type: array
          items:
            type: string
          description: The source integration for attribution
        attribution_status:
          type: array
          items:
            type: string
          description: Indicates if the attribution is organic or non-organic
        attribution_channel:
          type: array
          items:
            type: string
          description: Marketing channel that led to the transaction
        attribution_campaign:
          type: array
          items:
            type: string
          description: Marketing campaign that brought the transaction
        attribution_adgroup:
          type: array
          items:
            type: string
          description: Attribution ad group that brought the transaction
        attribution_adset:
          type: array
          items:
            type: string
          description: Attribution ad set that led to the transaction
        attribution_creative:
          type: array
          items:
            type: string
          description: Specific visual or text elements in an ad or campaign tracked to measure effectiveness
        offer_category:
          type: array
          items:
            type: string
          description: Specify the offer categories you want to retrieve data for
        offer_type:
          type: array
          items:
            type: string
          description: Specify the offer types you want to retrieve data for
        offer_id:
          type: array
          items:
            type: string
          description: Specify the specific offers you want to retrieve data for
    CohortSegment:
      type: object
      description: A cohort segment representing users who started in the same period
      properties:
        segment_start_date:
          type: string
          description: The start date of this cohort segment
        type:
          type: string
          description: Type of segment ('total' for aggregated data, 'single' for individual cohort)
        title:
          type: string
          description: Display title for this cohort segment
        total_installs:
          type: integer
          description: Total number of app installs in this cohort
        total_subscriptions:
          type: integer
          description: Total number of subscriptions in this cohort
        total_paid_subscribers:
          type: integer
          description: Total number of paid subscribers in this cohort
        total_revenue_usd:
          type: number
          description: Total revenue in USD for this cohort
        total_proceeds_usd:
          type: number
          description: Total proceeds in USD for this cohort (after store fees)
        total_net_revenue_usd:
          type: number
          description: Total net revenue in USD for this cohort
        total_anrpas_usd:
          type: number
          description: Total Average Revenue Per Active Subscriber (ANRPAS) in USD
        total_appas_usd:
          type: number
          description: Total Average Proceeds Per Active Subscriber (APPAS) in USD
        total_arpas_usd:
          type: number
          description: Total Average Revenue Per Active Subscriber (ARPAS) in USD
        total_anrppu_usd:
          type: number
          description: Total Average Revenue Per Paying User (ANRPPU) in USD
        total_apppu_usd:
          type: number
          description: Total Average Proceeds Per Paying User (APPPU) in USD
        total_arppu_usd:
          type: number
          description: Total Average Revenue Per Paying User (ARPPU) in USD
        total_anrpu_usd:
          type: number
          description: Total Average Revenue Per User (ANRPU) in USD
        total_appu_usd:
          type: number
          description: Total Average Proceeds Per User (APPU) in USD
        total_arpu_usd:
          type: number
          description: Total Average Revenue Per User (ARPU) in USD
        predict:
          type: object
          nullable: true
          description: Prediction data for this cohort (if available)
        values:
          type: array
          description: Array of period-based values showing cohort performance over time
          items:
            $ref: "#/components/schemas/CohortValue"
    CohortValue:
      type: object
      description: Individual period value within a cohort segment showing performance metrics for a specific time period
      properties:
        arpas_usd:
          type: number
          description: Average Revenue Per Active Subscriber in USD for this period
        appas_usd:
          type: number
          description: Average Proceeds Per Active Subscriber in USD for this period
        anrpas_usd:
          type: number
          description: Average Net Revenue Per Active Subscriber in USD for this period
        anrppu_usd:
          type: number
          description: Average Net Revenue Per Paying User in USD for this period
        apppu_usd:
          type: number
          description: Average Proceeds Per Paying User in USD for this period
        arppu_usd:
          type: number
          description: Average Revenue Per Paying User in USD for this period
        anrpu_usd:
          type: number
          description: Average Net Revenue Per User in USD for this period
        appu_usd:
          type: number
          description: Average Proceeds Per User in USD for this period
        arpu_usd:
          type: number
          description: Average Revenue Per User in USD for this period
        installs:
          type: integer
          description: Number of app installs in this period
        period:
          type: integer
          description: Period number (1 = first period, 2 = second period, etc.)
        revenue_usd:
          type: number
          description: Total revenue in USD for this period
        proceeds_usd:
          type: number
          description: Total proceeds in USD for this period (after store fees)
        net_revenue_usd:
          type: number
          description: Total net revenue in USD for this period
        revenue_relative:
          type: number
          description: Revenue as percentage relative to the first period (100% = first period)
        proceeds_relative:
          type: number
          description: Proceeds as percentage relative to the first period (100% = first period)
        net_revenue_relative:
          type: number
          description: Net revenue as percentage relative to the first period (100% = first period)
        subscriptions:
          type: integer
          description: Number of subscriptions in this period
        subscriptions_relative:
          type: number
          description: Subscriptions as percentage relative to the first period (100% = first period)
        subscribers:
          type: integer
          description: Number of subscribers in this period
        subscribers_relative:
          type: number
          description: Subscribers as percentage relative to the first period (100% = first period)
        currently_active_period:
          type: boolean
          description: Whether this is the currently active period for the cohort
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        You need to authenticate your API requests with your secret API key as an Authorization header. 
        You can find it in the App Settings. The format is `Api-Key {YOUR_SECRET_API_KEY}`, 
        for example: `Api-Key secret_live_...`.
```