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
paths:
  /api/v1/client-api/metrics/analytics/:
    post:
      summary: Retrieve analytics data
      description: "Retrieves analytics data for insights on user behavior and performance metrics to further use in charts.\n\nRate limit: 2 requests per second."
      operationId: retrieveAnalyticsData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsDataRequest'
            examples:
              basic:
                summary: Basic analytics data request
                value:
                  chart_id: "revenue"
                  filters:
                    date: ["2024-01-01", "2024-12-31"]
                    country: ["us"]
                    attribution_channel: ["social_media_influencers"]
                  period_unit: "week"
                  segmentation: "attribution_campaign"
      responses:
        '200':
          description: Analytics data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsDataResponse'
              example:
                data:
                  revenue:
                    data: []
                    value: 0.0
                    value_from: null
                    value_to: null
                    compare_value_from: null
                    compare_value_to: null
                    title: "revenue"
                    type: "multi"
                    default_aggregation: "sum"
                    description: "<div>Total money received from both subscriptions and one-time purchases. Does not include\nrevenue from subscriptions and purchases that were refunded afterward. Calculated before the store's fee.<br />\nFor example, there were 5 monthly $10 subs, 1 yearly $100 sub and 10 one-time $50 purchases today,<br />\nrevenue = 5*$10 + 1*$100 + 10*$50 = $650</div>"
                    metric_name: "Revenue"
                    is_json: true
                    unit: "USD"
                    recommended_period: null
                  proceeds:
                    data: []
                    value: 0.0
                    value_from: null
                    value_to: null
                    compare_value_from: null
                    compare_value_to: null
                    title: "revenue"
                    type: "multi"
                    default_aggregation: "sum"
                    description: "<div>Total money received from both subscriptions and one-time purchases. Does not include\nrevenue from subscriptions and purchases that were refunded afterward. Calculated before the store's fee.<br />\nFor example, there were 5 monthly $10 subs, 1 yearly $100 sub and 10 one-time $50 purchases today,<br />\nrevenue = 5*$10 + 1*$100 + 10*$50 = $650</div>"
                    metric_name: "Revenue"
                    is_json: true
                    unit: "USD"
                    recommended_period: null
                  net_revenue:
                    data: []
                    value: 0.0
                    value_from: null
                    value_to: null
                    compare_value_from: null
                    compare_value_to: null
                    title: "revenue"
                    type: "multi"
                    default_aggregation: "sum"
                    description: "<div>Total money received from both subscriptions and one-time purchases. Does not include\nrevenue from subscriptions and purchases that were refunded afterward. Calculated before the store's fee.<br />\nFor example, there were 5 monthly $10 subs, 1 yearly $100 sub and 10 one-time $50 purchases today,<br />\nrevenue = 5*$10 + 1*$100 + 10*$50 = $650</div>"
                    metric_name: "Revenue"
                    is_json: true
                    unit: "USD"
                    recommended_period: null
            text/csv:
              schema:
                type: string
                description: Analytics 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.

  /api/v1/client-api/metrics/cohort/:
    post:
      summary: Retrieve cohort data
      description: "Retrieve cohort data to track user groups over time.\n\nRate 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.0
                    total_proceeds_usd: 0.0
                    total_net_revenue_usd: 0.0
                    total_anrpas_usd: 0.0
                    total_appas_usd: 0.0
                    total_arpas_usd: 0.0
                    total_anrppu_usd: 0.0
                    total_apppu_usd: 0.0
                    total_arppu_usd: 0.0
                    total_anrpu_usd: 0.0
                    total_appu_usd: 0.0
                    total_arpu_usd: 0.0
                    predict: null
                    values:
                      - arpas_usd: 0.0
                        appas_usd: 0.0
                        anrpas_usd: 0.0
                        anrppu_usd: 0.0
                        apppu_usd: 0.0
                        arppu_usd: 0.0
                        anrpu_usd: 0.0
                        appu_usd: 0.0
                        arpu_usd: 0.0
                        installs: 0
                        period: 1
                        revenue_usd: 0.0
                        proceeds_usd: 0.0
                        net_revenue_usd: 0.0
                        revenue_relative: 0.0
                        proceeds_relative: 0.0
                        net_revenue_relative: 0.0
                        subscriptions: 0
                        subscriptions_relative: 0.0
                        subscribers: 0
                        subscribers_relative: 0.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.

  /api/v1/client-api/metrics/conversion/:
    post:
      summary: Retrieve conversion data
      description: "Retrieves conversion data to analyze user actions and measure the effectiveness of marketing efforts over time.\n\nRate limit: 2 requests per second."
      operationId: retrieveConversionData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionDataRequest'
            examples:
              basic:
                summary: Basic conversion data request
                value:
                  filters:
                    date: ["2024-01-01", "2024-12-31"]
                  from_period: 1
                  to_period: "6+"
                  period_unit: "month"
                  date_type: "purchase_date"
                  segmentation: "country"
                  format: "json"
      responses:
        '200':
          description: Conversion data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionDataResponse'
              example:
                data: []
                value: 0.0
                value_from: 0
                value_to: 0
                compare_value_from: null
                compare_value_to: null
                title: "Conversion rate from Paid to more than 6 months"
                type: "multi"
                default_aggregation: "sum"
                description: "If Х - the number of the 1st payments taken during the selected date, and Y - the amount of the renewals that happened after the 6 months since the selected date from those 1st payments, then Conversion = (Y / X) * 100%. For example, we had 100 1st subscriptions of various products on the 1st of January and among them 20 renewed on the 1st week of July (the 25th payment). On the 8th of July, we open the chart and see the conversion of the 1st of January = (20 / 100) * 100% = 20%. Then 30 more subscribers of the 1st of January renewed by the start of August (the 8th payment). We open the chart on the 1st of August and see that the conversion of the 1st of January = ((20+30) / 100) * 100% = 50%. This number shows which part of those who had their 1st payment on the 1st of January converted to the period > 6 months with any number of payments by the current moment."
                metric_name: "from_paid_to_6_months_conversion"
                is_json: true
                unit: "percent"
                recommended_period:
                  date_from: "2018-04-29"
                  date_to: "2024-12-31"
                  period_unit: "month"
            text/csv:
              schema:
                type: string
                description: Conversion 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.

  /api/v1/client-api/metrics/funnel/:
    post:
      summary: Retrieve funnel data
      description: "Retrieves funnel data to track user progression through specific stages of a conversion process.\n\nRate limit: 2 requests per second."
      operationId: retrieveFunnelData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FunnelDataRequest'
            examples:
              basic:
                summary: Basic funnel data request
                value:
                  filters:
                    date: ["2024-01-01", "2024-12-31"]
                    compare_date: ["2023-01-01", "2023-12-31"]
                    offer_category: ["promotional"]
                  period_unit: "quarter"
                  show_value_as: "absolute"
                  format: "csv"
      responses:
        '200':
          description: Funnel data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunnelDataResponse'
              example:
                data:
                  - title: "Total"
                    type: "total"
                    values:
                      - period: -2
                        title: "Install"
                        value: 2
                        value_relative: 100.0
                        relative_changes: 0.0
                        following_changes:
                          title: "Drop off"
                          value: 2
                          value_relative: 100.0
                        churn_reason_title: ""
                        churn_reasons: []
                        values: []
                      - period: -1
                        title: "Paywall displayed"
                        value: 0
                        value_relative: 0.0
                        relative_changes: 0.0
                        following_changes:
                          title: "Drop off"
                          value: 0
                          value_relative: 0.0
                        churn_reason_title: ""
                        churn_reasons: []
                        values: []
            text/csv:
              schema:
                type: string
                description: Funnel 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.

  /api/v1/client-api/metrics/ltv/:
    post:
      summary: Retrieve Lifetime Value (LTV) data
      description: "Retrieves LTV data to assess the long-term revenue potential of customers over their engagement period.\n\nRate limit: 2 requests per second."
      operationId: retrieveLTVData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LTVDataRequest'
            examples:
              basic:
                summary: Basic LTV data request
                value:
                  filters:
                    date: ["2024-01-01", "2024-12-31"]
                    compare_date: ["2023-01-01", "2023-12-31"]
                    offer_category: ["introductory"]
                    store: ["app_store"]
                    country: ["us"]
                    attribution_source: ["appsflyer"]
                    attribution_status: ["organic"]
                    attribution_channel: ["social_media"]
                  period_unit: "quarter"
                  period_type: "renewals"
                  segmentation: "store_product_id"
                  format: "csv"
      responses:
        '200':
          description: LTV data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LTVDataResponse'
              example:
                revenue:
                  data:
                    - title: "Total"
                      type: "total"
                      value: 0.0
                      values: []
                      cohort_size: 0
                  description: "<div>LTV (Lifetime Value) is calculated as revenue for the period / number of subscribers on start.\n It's an actual, not predicted LTV.\n <a target=\"_blank\" rel=\"noopener noreferrer\" href='https://adapty.io/docs/ltv'> Read more</a>.</div>"
                  value: 0.0
                  unit: "USD"
                  title: "LTV"
                proceeds:
                  data:
                    - title: "Total"
                      type: "total"
                      value: 0.0
                      values: []
                      cohort_size: 0
                  description: "<div>LTV (Lifetime Value) is calculated as revenue for the period / number of subscribers on start.\n It's an actual, not predicted LTV.\n <a target=\"_blank\" rel=\"noopener noreferrer\" href='https://adapty.io/docs/ltv'> Read more</a>.</div>"
                  value: 0.0
                  unit: "USD"
                  title: "LTV"
                net_revenue:
                  data:
                    - title: "Total"
                      type: "total"
                      value: 0.0
                      values: []
                      cohort_size: 0
                  description: "<div>LTV (Lifetime Value) is calculated as revenue for the period / number of subscribers on start.\n It's an actual, not predicted LTV.\n <a target=\"_blank\" rel=\"noopener noreferrer\" href='https://adapty.io/docs/ltv'> Read more</a>.</div>"
                  value: 0.0
                  unit: "USD"
                  title: "LTV"
            text/csv:
              schema:
                type: string
                description: LTV 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.

  /api/v1/client-api/metrics/retention/:
    post:
      summary: Retrieve retention data
      description: "Retrieves the retention data to analyze the ability of a product to keep users engaged over time.\n\nRate limit: 2 requests per second."
      operationId: retrieveRetentionData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetentionDataRequest'
            examples:
              basic:
                summary: Basic retention data request
                value:
                  filters:
                    date: ["2024-01-01", "2024-12-31"]
                    compare_date: ["2023-01-01", "2023-12-31"]
                  period_unit: "quarter"
                  period_type: "renewals"
                  segmentation: "store_product_id"
                  format: "csv"
      responses:
        '200':
          description: Retention data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetentionDataResponse'
              example:
                data: []
                title: "Subscription retention"
                metric_name: "Subscription retention"
                description: "Absolute value is the amount of users who entered the current step - subscribed for a trial or paid for a subscription. Relative is calculated as a percentage of these users among those who got a trial. So it starts with 100% for the trial step."
                value_type: null
            text/csv:
              schema:
                type: string
                description: Retention 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.

  /api/v1/client-api/exports/placements/:
    post:
      summary: Retrieve placement info
      description: "Retrieves information about paywall or onboarding placements: paywalls, segments, audiences, and A/B tests. This can help you ensure everything is set up correctly without having to open each placement you have separately.\n\nRate limit: 2 requests per second."
      operationId: retrievePlacementInfo
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlacementInfoRequest'
            examples:
              basic:
                summary: Basic placement info request
                value:
                  filters:
                    placement_type: "paywall"
      responses:
        '200':
          description: Placement information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacementInfoResponse'
            text/csv:
              schema:
                type: string
                description: Placement information 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:
  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_...`.

  schemas:
    AnalyticsDataRequest:
      type: object
      required:
        - chart_id
        - filters
      properties:
        chart_id:
          type: string
          enum: [revenue, mrr, arr, arppu, subscriptions_active, subscriptions_new, subscriptions_renewal_cancelled, subscriptions_expired, trials_active, trials_new, trials_renewal_cancelled, trials_expired, grace_period, billing_issue, refund_events, refund_money, non_subscriptions, arpu, installs]
          description: Specify which chart you need. You can specify only one chart type in each request.
          example: "revenue"
        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"
        date_type:
          type: string
          enum: [purchase_date, profile_install_date]
          description: Specify which date should be treated as a user joining date
          default: "purchase_date"
        segmentation:
          type: string
          description: Sets the basis for segmentation
        format:
          type: string
          enum: [json, csv]
          description: Specify the export file format
          default: "json"

    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"

    ConversionDataRequest:
      type: object
      required:
        - filters
        - from_period
        - to_period
      properties:
        filters:
          $ref: '#/components/schemas/MetricsFilters'
        from_period:
          oneOf:
            - type: string
            - type: "null"
          description: The user's starting subscription state of the conversation
        to_period:
          type: string
          description: The user's new subscription state after the conversion
        period_unit:
          type: string
          enum: [day, week, month, quarter, year]
          description: Specify the time interval for aggregating analytics data
          default: "month"
        date_type:
          type: string
          enum: [purchase_date, profile_install_date]
          description: Specify which date should be treated as a user joining date
          default: "purchase_date"
        segmentation:
          type: string
          description: Sets the basis for segmentation
        format:
          type: string
          enum: [json, csv]
          description: Specify the export file format
          default: "json"

    FunnelDataRequest:
      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
        show_value_as:
          type: string
          enum: [absolute, relative, both]
          description: Specify how values are displayed
        segmentation:
          type: string
          description: Sets the basis for segmentation
        format:
          type: string
          enum: [json, csv]
          description: Specify the export file format
          default: "json"

    LTVDataRequest:
      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
        period_type:
          type: string
          enum: [renewals, days]
          description: Analyze data by renewals or by days
        segmentation:
          type: string
          description: Sets the basis for segmentation
        format:
          type: string
          enum: [json, csv]
          description: Specify the export file format
          default: "json"

    RetentionDataRequest:
      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
        segmentation:
          type: string
          description: Sets the basis for segmentation
        use_trial:
          type: boolean
          description: Boolean indicating whether a trial was used
          default: false
        format:
          type: string
          enum: [json, csv]
          description: Specify the export file format
          default: "json"

    PlacementInfoRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          type: object
          required:
            - placement_type
          properties:
            placement_type:
              type: string
              enum: [paywall, onboarding]
              description: Filter which placements will be sent in the response

    PlacementInfoResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              developer_id:
                type: string
                description: Placement ID
              placement_name:
                type: string
                description: Placement name
              audience_name:
                type: string
                description: Audience name
              segment_name:
                type: string
                description: Audience ID
              cross_placement_ab_test_name:
                type: string
                nullable: true
                description: Cross-placement A/B test name
              ab_test_name:
                type: string
                nullable: true
                description: A/B test name
              paywall_name:
                type: string
                description: Paywall name (only returned if placement_type is paywall)
              onboarding_name:
                type: string
                description: Onboarding name (only returned if placement_type is onboarding)

    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

    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

    AnalyticsDataResponse:
      type: object
      description: Response containing analytics data for the requested chart type
      properties:
        data:
          type: object
          description: Object containing different metric types (revenue, proceeds, net_revenue, etc.)
          additionalProperties:
            $ref: '#/components/schemas/MetricData'

    MetricData:
      type: object
      description: Individual metric data containing values, descriptions, and metadata
      properties:
        data:
          type: array
          description: Array of data points for the metric (can be empty for aggregated metrics)
          items:
            type: object
        value:
          type: number
          description: The main value for this metric
        value_from:
          type: number
          nullable: true
          description: Starting value for the period (if applicable)
        value_to:
          type: number
          nullable: true
          description: Ending value for the period (if applicable)
        compare_value_from:
          type: number
          nullable: true
          description: Starting value for comparison period (if applicable)
        compare_value_to:
          type: number
          nullable: true
          description: Ending value for comparison period (if applicable)
        title:
          type: string
          description: Display title for the metric
        type:
          type: string
          description: Type of metric (e.g., 'multi', 'single')
        default_aggregation:
          type: string
          description: Default aggregation method (e.g., 'sum', 'average')
        description:
          type: string
          description: HTML description explaining what this metric represents and how it's calculated
        metric_name:
          type: string
          description: Internal name of the metric
        is_json:
          type: boolean
          description: Whether the data is in JSON format
        unit:
          type: string
          description: Unit of measurement (e.g., 'USD', 'percent')
        recommended_period:
          type: object
          nullable: true
          description: Recommended date range for this metric
          properties:
            date_from:
              type: string
              description: Start date of recommended period
            date_to:
              type: string
              description: End date of recommended period
            period_unit:
              type: string
              description: Recommended period unit (day, week, month, etc.)

    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'

    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

    ConversionDataResponse:
      type: object
      description: Response containing conversion data showing user progression between subscription states
      properties:
        data:
          type: array
          description: Array of conversion data points (can be empty for aggregated metrics)
          items:
            type: object
        value:
          type: number
          description: The conversion rate value
        value_from:
          type: integer
          description: Starting subscription state for the conversion
        value_to:
          type: integer
          description: Target subscription state for the conversion
        compare_value_from:
          type: number
          nullable: true
          description: Starting value for comparison period
        compare_value_to:
          type: number
          nullable: true
          description: Ending value for comparison period
        title:
          type: string
          description: Display title describing the conversion type
        type:
          type: string
          description: Type of conversion metric
        default_aggregation:
          type: string
          description: Default aggregation method for this metric
        description:
          type: string
          description: Detailed explanation of how the conversion rate is calculated
        metric_name:
          type: string
          description: Internal name of the conversion metric
        is_json:
          type: boolean
          description: Whether the data is in JSON format
        unit:
          type: string
          description: Unit of measurement (typically 'percent' for conversion rates)
        recommended_period:
          type: object
          description: Recommended date range for this conversion metric
          properties:
            date_from:
              type: string
              description: Start date of recommended period
            date_to:
              type: string
              description: End date of recommended period
            period_unit:
              type: string
              description: Recommended period unit

    FunnelDataResponse:
      type: object
      description: Response containing funnel analysis data showing user progression through conversion stages
      properties:
        data:
          type: array
          description: Array of funnel segments showing different stages of the conversion process
          items:
            $ref: '#/components/schemas/FunnelSegment'

    FunnelSegment:
      type: object
      description: A funnel segment representing a stage in the conversion process
      properties:
        title:
          type: string
          description: Display title for this funnel segment
        type:
          type: string
          description: Type of funnel segment ('total' for aggregated data)
        values:
          type: array
          description: Array of funnel values showing progression through stages
          items:
            $ref: '#/components/schemas/FunnelValue'

    FunnelValue:
      type: object
      description: Individual funnel stage value showing user progression and drop-off
      properties:
        period:
          type: integer
          description: Period number in the funnel (-2 = Install, -1 = Paywall displayed, etc.)
        title:
          type: string
          description: Display title for this funnel stage
        value:
          type: integer
          description: Number of users who reached this stage
        value_relative:
          type: number
          description: Percentage of users who reached this stage relative to the first stage
        relative_changes:
          type: number
          description: Change in conversion rate compared to previous period
        following_changes:
          type: object
          description: Information about users who dropped off after this stage
          properties:
            title:
              type: string
              description: Title for the drop-off stage
            value:
              type: integer
              description: Number of users who dropped off
            value_relative:
              type: number
              description: Percentage of users who dropped off
        churn_reason_title:
          type: string
          description: Title describing the reason for churn at this stage
        churn_reasons:
          type: array
          description: Array of specific churn reasons
          items:
            type: object
        values:
          type: array
          description: Additional nested values for this funnel stage
          items:
            type: object

    LTVDataResponse:
      type: object
      description: Response containing Lifetime Value (LTV) data for different revenue types
      properties:
        revenue:
          $ref: '#/components/schemas/LTVMetric'
          description: LTV calculated using gross revenue
        proceeds:
          $ref: '#/components/schemas/LTVMetric'
          description: LTV calculated using proceeds (after store fees)
        net_revenue:
          $ref: '#/components/schemas/LTVMetric'
          description: LTV calculated using net revenue

    LTVMetric:
      type: object
      description: Individual LTV metric containing cohort data and calculations
      properties:
        data:
          type: array
          description: Array of LTV data points for different cohorts
          items:
            $ref: '#/components/schemas/LTVData'
        description:
          type: string
          description: HTML description explaining how LTV is calculated
        value:
          type: number
          description: The overall LTV value
        unit:
          type: string
          description: Unit of measurement (typically 'USD')
        title:
          type: string
          description: Display title for this LTV metric

    LTVData:
      type: object
      description: Individual LTV data point for a specific cohort
      properties:
        title:
          type: string
          description: Display title for this LTV data point
        type:
          type: string
          description: Type of LTV data ('total' for aggregated data)
        value:
          type: number
          description: LTV value for this cohort
        values:
          type: array
          description: Array of period-based LTV values
          items:
            type: object
        cohort_size:
          type: integer
          description: Number of users in this cohort

    RetentionDataResponse:
      type: object
      description: Response containing retention data showing user engagement over time
      properties:
        data:
          type: array
          description: Array of retention data points (can be empty for some retention types)
          items:
            type: object
        title:
          type: string
          description: Display title for the retention metric
        metric_name:
          type: string
          description: Internal name of the retention metric
        description:
          type: string
          description: Explanation of how retention is calculated (absolute vs relative values)
        value_type:
          type: string
          nullable: true
          description: Type of retention value (absolute or relative)

security:
  - apikeyAuth: []