POST /api/v1/client-api/metrics/retention/

Retrieve retention data

Copy as Markdown

Retrieves the retention data to analyze the ability of a product to keep users engaged over time.

Rate limit: 2 requests per second.

Request body

filtersobjectrequired

datearray of stringrequired

Enter the date or time period for which you want to retrieve chart data

compare_datearray of string

Enter the comparison date or time period

storearray of string

Filter by the app store where the purchase was made

countryarray of string

Filter by the 2-letter country code where the purchase took place

store_product_idarray of string

Store-qualified product ID, formatted as <store>:<product_id> — for example app_store:premium_monthly or play_store:premium_sub:monthly-base-plan for a Google subscription with a base plan. A bare product ID with no store prefix is rejected.

durationarray of string

Specify the subscription duration

attribution_sourcearray of string

The source integration for attribution

attribution_statusarray of string

Indicates if the attribution is organic or non-organic

attribution_channelarray of string

Marketing channel that led to the transaction

attribution_campaignarray of string

Marketing campaign that brought the transaction

attribution_adgrouparray of string

Attribution ad group that brought the transaction

attribution_adsetarray of string

Attribution ad set that led to the transaction

attribution_creativearray of string

Specific visual or text elements in an ad or campaign tracked to measure effectiveness

offer_categoryarray of string

Specify the offer categories you want to retrieve data for

offer_typearray of string

Specify the offer types you want to retrieve data for

offer_idarray of string

Specify the specific offers you want to retrieve data for

placement_idarray of string

Adapty's internal IDs of the placements to retrieve data for — the UUID in the placement's dashboard URL, not the placement ID you pass to the SDK

audience_idarray of string

Adapty's internal IDs of the placement audiences to retrieve data for

paywall_idarray of string

Adapty's internal IDs of the paywalls to retrieve data for — the UUID in the paywall's dashboard URL

flow_idarray of string

Adapty's internal IDs of the flows to retrieve data for — the UUID in the flow's dashboard URL

flow_screen_idarray of string

Flow screens to retrieve data for, each formatted as <flow_id>:<screen_id> — for example 3f8a1c2e-0b7d-4e5a-9c61-2d4f8e7b1a90:paywall

segment_idarray of string

Adapty's internal IDs of the segments to retrieve data for

segmentationstring

Splits the data into one series per value of this dimension. For example, flow_id returns a separate series for each flow, and placement_id for each placement.

One of: "period", "renewal_status", "cancellation_reason", "store_product_id", "country", "store", "paywall_id", "audience_id", "placement_id", "flow_id", "flow_screen_id", "segment_id", "duration", "offer_category", "offer_type", "offer_id", "attribution_source", "attribution_status", "attribution_channel", "attribution_campaign", "attribution_adgroup", "attribution_adset", "attribution_creative", "day", "week", "month", "year"

use_trialboolean

Boolean indicating whether a trial was used

formatstring

Specify the export file format

One of: "json", "csv"

Responses

Retention data retrieved successfully

Schema

Response containing retention data showing user engagement over time

dataarray of object

Array of retention data points (can be empty for some retention types)

titlestring

Display title for the retention metric

metric_namestring

Internal name of the retention metric

descriptionstring

Explanation of how retention is calculated (absolute vs relative values)

value_typestring

Type of retention value (absolute or relative)

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
}

Bad Request

Schema

errorsarray of object

sourcestring

errorsarray of string

error_codestring

status_codeinteger

Unauthorized

Schema

errorsarray of object

sourcestring

errorsarray of string

error_codestring

status_codeinteger

Rate limit exceeded. Maximum 2 requests per second per app, shared by all of the app's API keys.

Try it

Authorization

Body

curl --request POST \
  --url 'https://api-admin.adapty.io/api/v1/client-api/metrics/retention/' \
  --header 'Authorization: Api-Key YOUR_SECRET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
      "date": [
        "2024-01-01",
        "2024-12-31"
      ],
      "compare_date": [
        "2023-01-01",
        "2023-12-31"
      ]
    },
    "segmentation": "store_product_id",
    "format": "csv"
  }'

const response = await fetch('https://api-admin.adapty.io/api/v1/client-api/metrics/retention/', {
  method: 'POST',
  headers: {
    'Authorization': 'Api-Key YOUR_SECRET_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filters": {
      "date": [
        "2024-01-01",
        "2024-12-31"
      ],
      "compare_date": [
        "2023-01-01",
        "2023-12-31"
      ]
    },
    "segmentation": "store_product_id",
    "format": "csv"
  }),
});
const data = await response.json();

import requests

response = requests.post('https://api-admin.adapty.io/api/v1/client-api/metrics/retention/', headers={
    'Authorization': 'Api-Key YOUR_SECRET_API_KEY',
    'Content-Type': 'application/json',
}, json={
      "filters": {
        "date": [
          "2024-01-01",
          "2024-12-31"
        ],
        "compare_date": [
          "2023-01-01",
          "2023-12-31"
        ]
      },
      "segmentation": "store_product_id",
      "format": "csv"
    })
data = response.json()