# Retrieve conversion data

> Retrieves conversion data to analyze user actions and measure the effectiveness of marketing efforts over time.
>
> Rate limit: 2 requests per second.

## OpenAPI

```yaml
/api-specs/export-analytics-api.yaml post /api/v1/client-api/metrics/conversion/
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/conversion/:
    post:
      summary: Retrieve conversion data
      description: |-
        Retrieves conversion data to analyze user actions and measure the effectiveness of marketing efforts over time.

        Rate 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
                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.
components:
  schemas:
    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
    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
    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
  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_...`.
```