% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/st_ratings_review_facets.R
\name{st_reviews_by_rating_facets}
\alias{st_reviews_by_rating_facets}
\title{Fetch Review Metrics by Rating from Sensor Tower's Facets API}
\usage{
st_reviews_by_rating_facets(
  app_id,
  breakdown = c("date", "review_rating"),
  start_date,
  end_date,
  date_granularity = NULL,
  regions = NULL,
  languages = NULL,
  review_keywords = NULL,
  review_sentiments = NULL,
  review_tags = NULL,
  search_terms = NULL,
  rating_filters = NULL,
  auth_token = NULL,
  verbose = FALSE
)
}
\arguments{
\item{app_id}{Single iOS app ID or Android package name.}

\item{breakdown}{Breakdown fields or a comma-separated breakdown string.
Supported combinations are `"review_rating"`, `"date,review_rating"`,
`"region,review_rating"`, `"language,review_rating"`, and
`"app_version,review_rating"`.}

\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{date_granularity}{Optional date granularity. Required when
`breakdown` includes `date`.}

\item{regions}{Optional character vector of iOS region codes.}

\item{languages}{Optional character vector of Android language codes.}

\item{review_keywords}{Optional character vector of review-keyword filters.}

\item{review_sentiments}{Optional character vector of sentiment filters.}

\item{review_tags}{Optional character vector of review-tag filters.}

\item{search_terms}{Optional character vector of content search terms.}

\item{rating_filters}{Optional character vector or integer vector of star
filters (`1` through `5`).}

\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] containing fields such as
  `review_rating`, `review_rating_count`, `review_rating_percentage`, and
  `review_rating_average`.
}
\description{
Retrieves review metrics broken down by star rating from Sensor Tower's new
facets-based review endpoint. This wrapper targets
`"/v1/facets/metrics?facets=reviews_by_rating"`.
}
\details{
Validated against the live Sensor Tower API on March 17, 2026.
}
\examples{
\dontrun{
reviews <- st_reviews_by_rating_facets(
  app_id = "553834731",
  breakdown = c("date", "review_rating"),
  start_date = "2024-01-01",
  end_date = "2024-01-07",
  date_granularity = "day",
  regions = "US"
)
}

}
\seealso{
[st_facets_metrics()] for raw facets access
}
