% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/st_facets_metrics.R
\name{st_facets_metrics}
\alias{st_facets_metrics}
\title{Low-Level Access to Sensor Tower Facets Metrics}
\usage{
st_facets_metrics(
  query = character(),
  params = list(),
  auth_token = NULL,
  host = c("api", "app"),
  verbose = FALSE
)
}
\arguments{
\item{query}{Character vector of raw query fragments appended verbatim after
encoded `params`. This is useful when Sensor Tower documents nested or
repeated parameters that are awkward to express as a regular named R list.
Example: `c("filters[app_ids][]=553834731")`.}

\item{params}{Named list of regular query parameters. Vector values are
serialized as comma-separated strings to match Sensor Tower's
`style=form, explode=false` usage in the OpenAPI spec.}

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

\item{host}{Character string. Which host to target: `"api"` (default) or
`"app"`. The `app` host uses `https://app.sensortower.com/api`.}

\item{verbose}{Logical. If `TRUE`, prints the request URL with the auth token
redacted.}
}
\value{
A parsed JSON response. Rectangular top-level responses are returned
  as a tibble; nested responses are returned as a named list.
}
\description{
Performs a GET request against Sensor Tower's `"/v1/facets/metrics"` route.
This helper stays intentionally low-level so package code can work with new
facets-based endpoints while higher-level wrappers are added incrementally.
}
\details{
As of March 17, 2026, the facets route is live and the retention contract is
validated against production. The machine-readable Sensor Tower docs remain
gated behind a signed-in web session, so this helper still provides a stable
escape hatch for raw or partially documented facets requests.
}
\examples{
\dontrun{
# Retention request using regular query parameters
response <- st_facets_metrics(
  params = list(
    facets = "retention",
    bundle = "retention_daily",
    breakdown = c("date", "app_id"),
    start_date = "2025-01-01",
    end_date = "2025-01-31",
    app_ids = "553834731"
  )
)
}

}
