---
title: "Distribution of currently-active devices by release version."
method: GET
path: "/apps/{appId}/metrics/version-distribution"
tags: ["metrics"]
---

# Distribution of currently-active devices by release version.

`GET /apps/{appId}/metrics/version-distribution`

## Request

- Base URL: `https://api.shorebird.dev/api/v1`
- URL: `https://api.shorebird.dev/api/v1/apps/{appId}/metrics/version-distribution`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Returns the exact (non-HLL) count of currently-active devices for
the app, grouped by `release_version`. "Currently active" is
bounded by a server-side active-device window; rows with no
reported `release_version` are returned with `releaseVersion: null`
and represent devices on Flutter versions too old to emit the
field. The result is sorted by `deviceCount` descending, then
`releaseVersion` ascending with NULLs last.

## Response `200`

The version distribution for the app.

- GetVersionDistributionResponse: The response body for GET /apps/{appId}/metrics/version-distribution.
  - `entries` VersionDistributionEntry[], required: One entry per release version, sorted by `device_count` descending, then `release_version` ascending with NULLs last.
    - `release_version` string, nullable, required: The release version for this bucket, or null for devices whose client did not emit one.
    - `device_count` integer, required: Number of currently-active devices on this release version within the active-device window.
    - `percentage` number, double, required: Fractional share of currently-active devices on this release version, in [0.0, 1.0]. Server is the source of truth; clients should render this value rather than recomputing it.
  - `total_devices` integer, required: Sum of `device_count` across all entries. Convenience for clients; matches the server-side sum used to compute `percentage`.
  - `active_window_days` integer, required: The active-device window in days that bounds the query. Hardcoded server-side in v1; tier-gated per-caller windows land in a follow-up.
  - `as_of` string, date-time, required: Server's UTC timestamp at the moment the response was constructed. Not a freshness indicator for the underlying data, which is refreshed by an hourly scheduled query and may lag by up to ~1 hour.

## Other responses

- `default`: Standard error response. Emitted for any non-2xx status where a body can be decoded into an [ErrorResponse].

---

[API](https://skmtc.dev/shorebird/apis/shorebird-codepush-api.md) - [All operations](https://skmtc.dev/shorebird/apis/shorebird-codepush-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shorebird/apis/shorebird-codepush-api/revisions/941da8871d10?raw)