# Retrieve retention data

> Retrieves the retention data to analyze the ability of a product to keep users engaged over time.
>
> Rate limit: 2 requests per second.

## OpenAPI

```yaml
/api-specs/export-analytics-api.yaml post /api/v1/client-api/metrics/retention/
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/retention/:
    post:
      summary: Retrieve retention data
      description: |-
        Retrieves the retention data to analyze the ability of a product to keep users engaged over time.

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