st_retention_facets: Fetch Retention Metrics from Sensor Tower's Facets API

In sensortowerR: Interface to 'Sensor Tower' Mobile App Intelligence API

Fetch Retention Metrics from Sensor Tower's Facets API

Description

Retrieves retention curves from Sensor Tower's new facets-based retention endpoint. This wrapper targets '"/v1/facets/metrics?facets=retention"' and returns a tidy tibble with the live response columns preserved.

Usage

st_retention_facets(
  app_ids = NULL,
  unified_app_ids = NULL,
  bundle = c("retention_daily", "retention_weekly", "retention_monthly"),
  breakdown = c("date", "app_id"),
  start_date,
  end_date,
  regions = NULL,
  auth_token = NULL,
  verbose = FALSE
)

Arguments

app_ids	Character vector of platform-specific app IDs. May contain iOS numeric IDs or Android bundle IDs. Supply exactly one of 'app_ids' or 'unified_app_ids'.
unified_app_ids	Character vector of Sensor Tower unified app IDs. Supply exactly one of 'app_ids' or 'unified_app_ids'.
bundle	Character string. Retention bundle to request: '"retention_daily"', '"retention_weekly"', or '"retention_monthly"'.
breakdown	Character vector of breakdown fields. Supported combinations are the ones documented by Sensor Tower: '"date"', '"app_id"', '"unified_app_id"', '"date,app_id"', '"date,unified_app_id"', '"unified_app_id,app_id"', and '"date,unified_app_id,app_id"'.
start_date	Start date in 'YYYY-MM-DD' format or as 'Date'.
end_date	End date in 'YYYY-MM-DD' format or as 'Date'.
regions	Optional character vector of region codes. When omitted, Sensor Tower returns worldwide estimates.
auth_token	Optional. Character string. Your Sensor Tower API token. Defaults to environment variable 'SENSORTOWER_AUTH_TOKEN'.
verbose	Logical. If 'TRUE', prints the request URL with the auth token redacted.

Details

Validated against the live Sensor Tower API on March 17, 2026. The production response currently returns daily retention columns including 'est_retention_d14' and 'est_retention_d365'.

Value

A [tibble][tibble::tibble] with one row per requested breakdown combination. The response preserves Sensor Tower's live metric column names such as 'est_retention_d1', 'est_retention_d14', 'est_retention_w52', or 'est_retention_m12'.

See Also

[st_retention()] for the legacy retention endpoint, [st_facets_metrics()] for raw facets access

Examples

## Not run: 
retention <- st_retention_facets(
  app_ids = "553834731",
  bundle = "retention_daily",
  breakdown = c("date", "app_id"),
  start_date = "2025-01-01",
  end_date = "2025-01-31"
)

## End(Not run)

sensortowerR documentation built on March 18, 2026, 5:07 p.m.