---
title: "Cumulative patch-adoption curves for a release."
method: GET
path: "/apps/{appId}/metrics/patch-adoption"
tags: ["metrics"]
---

# Cumulative patch-adoption curves for a release.

`GET /apps/{appId}/metrics/patch-adoption`

## Request

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

Returns, for a single release, the cumulative adoption of each patch:
the distinct devices running patch `>= N` (an HLL count over
`hourly_user_sketches`) over the patch's *target* — the distinct
devices on the release whose platform the patch was built for. Adoption
percentages are computed server-side and clamped to `[0.0, 1.0]`;
clients should render them rather than recompute.

Values are cumulative ("patch `>= N`"), so they are monotonic
non-increasing in `patch_number`.

The release is the `release_version` query parameter, or — when
omitted — the app's latest release by creation date (`is_latest` flags
that case). The window defaults to the last 28 days and is capped at 450
days (the effective window is echoed in `range`). With `granularity`
omitted, each patch carries a single full-window value (`period: null`);
set it for a curve at that resolution.

## Query parameters

- `release_version` string
- `start` string, date-time
- `end` string, date-time
- `granularity` 'hour' | 'day' | 'week': The bucket resolution of a metrics time series.

## Response `200`

The patch-adoption data for one release.

- GetPatchAdoptionResponse: The response body for GET /apps/{appId}/metrics/patch-adoption. Covers exactly one release.
  - `release_version` string, required: The release version this response is for.
  - `is_latest` boolean, required: True when the release was resolved via the "latest release by creation date" default (no `release_version` was supplied).
  - `granularity` string, nullable, required: The bucket resolution (`hour`, `day`, or `week`), or null when each patch carries a single full-window value.
  - `range` MetricsRange, required: The effective (post-default, post-clamp) window a metrics response — or one window of a metrics envelope — covers. Always echoed by the server; clients must treat it as authoritative rather than reusing the requested range.
    - `start` string, date-time, required: Window start (UTC, inclusive).
    - `end` string, date-time, required: Window end (UTC, exclusive).
  - `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.
  - `patches` PatchAdoptionEntry[], required: One entry per patch of the release.
    - `patch_number` integer, required: The patch number these cumulative values are anchored at.
    - `target_platforms` ReleasePlatform[], required: The platform(s) the patch was built for (from its artifacts). The denominator counts only devices on these platforms.
    - `is_rolled_back` boolean, required: Whether the patch has been rolled back.
    - `series` PatchAdoptionPoint[], required: The adoption series. Exactly one point (`period: null`) when no granularity was requested; otherwise one point per bucket, ordered by `period` ascending.
      - `period` string, date-time, nullable, required: The bucket start (UTC), or null when the response is a single full-window value (no granularity requested).
      - `devices` integer, required: Distinct devices running patch `>= patch_number` on the patch's target platform(s) within this bucket (an HLL count).
      - `target` integer, required: Distinct devices on the release whose platform the patch targets — the patch's reachable denominator — within this bucket.
      - `adoption_pct` number, double, required: `devices / target`, in [0.0, 1.0] (0 when `target` is 0). Server is the source of truth; clients should render this value rather than recomputing it.

## 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)