st_facets_metrics: Low-Level Access to Sensor Tower Facets Metrics

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

Low-Level Access to Sensor Tower Facets Metrics

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.

Usage

st_facets_metrics(
  query = character(),
  params = list(),
  auth_token = NULL,
  host = c("api", "app"),
  verbose = FALSE
)

Arguments

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")'.
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.
auth_token	Optional. Character string. Your Sensor Tower API token. Defaults to environment variable 'SENSORTOWER_AUTH_TOKEN'.
host	Character string. Which host to target: '"api"' (default) or '"app"'. The 'app' host uses 'https://app.sensortower.com/api'.
verbose	Logical. If 'TRUE', prints the request URL with the auth token redacted.

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.

Value

A parsed JSON response. Rectangular top-level responses are returned as a tibble; nested responses are returned as a named list.

Examples

## Not run: 
# 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"
  )
)

## End(Not run)

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