% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/st_retention_facets.R
\name{st_retention_facets}
\alias{st_retention_facets}
\title{Fetch Retention Metrics from Sensor Tower's Facets API}
\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{
\item{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`.}

\item{unified_app_ids}{Character vector of Sensor Tower unified app IDs.
Supply exactly one of `app_ids` or `unified_app_ids`.}

\item{bundle}{Character string. Retention bundle to request:
`"retention_daily"`, `"retention_weekly"`, or `"retention_monthly"`.}

\item{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"`.}

\item{start_date}{Start date in `YYYY-MM-DD` format or as `Date`.}

\item{end_date}{End date in `YYYY-MM-DD` format or as `Date`.}

\item{regions}{Optional character vector of region codes. When omitted,
Sensor Tower returns worldwide estimates.}

\item{auth_token}{Optional. Character string. Your Sensor Tower API token.
Defaults to environment variable `SENSORTOWER_AUTH_TOKEN`.}

\item{verbose}{Logical. If `TRUE`, prints the request URL with the auth token
redacted.}
}
\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`.
}
\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.
}
\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`.
}
\examples{
\dontrun{
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"
)
}

}
\seealso{
[st_retention()] for the legacy retention endpoint,
  [st_facets_metrics()] for raw facets access
}
