--- title: "Patch downloads for an app over a window." method: GET path: "/apps/{appId}/metrics/patch-downloads" tags: ["metrics"] --- # Patch downloads for an app over a window. `GET /apps/{appId}/metrics/patch-downloads` ## Request - Base URL: `https://api.shorebird.dev/api/v1` - URL: `https://api.shorebird.dev/api/v1/apps/{appId}/metrics/patch-downloads` - Auth: one of: - HTTP bearer - HTTP bearer Returns patch downloads for the app over a time window — summed over hourly counts — as a current/previous envelope, identical in shape to `patch-installs`: `current` covers the effective window, `previous` the equal-length window immediately preceding it. With `granularity` set, each window carries a `time_series`; with `group_by=release` set, `current` carries a per-release `breakdown`. `previous` never carries a breakdown. The window defaults to the last 28 days and starts no earlier than 2025-04-01, when counting began; the effective range is echoed in each window's `range`. ## Query parameters - `start` string, date-time - `end` string, date-time - `granularity` 'hour' | 'day' | 'week': The bucket resolution of a metrics time series. - `group_by` 'release' ## Response `200` The patch-downloads metric for the app. - GetPatchMetricResponse: The response body for the patch-installs and patch-downloads metric endpoints (app- and release-scoped): a current/previous envelope. `previous` covers the equal-length window immediately preceding `current`; period-over-period deltas are client display logic over the two totals. `previous` is omitted only when the prior window predates the data floor (no comparison data exists). When it reaches past the plan's metrics-history horizon, `previous` is still present with its total — the delta renders — but without a `time_series` (no prior-window overlay): granular history is the resolution the horizon gates, the scalar comparison is not. - `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 job and may lag by up to ~1 hour. - `granularity` string, nullable, required: The time-series bucket resolution (`hour`, `day`, or `week`), or null when no time series was requested. Applies to both windows. - `current` PatchMetricCurrentWindow, required: One window of the patch-metric envelope: the summed count over the window's effective range, with a per-bucket series when a `granularity` was requested. This base atom is the full shape of `previous`; `current` extends it (see PatchMetricCurrentWindow). - `count` integer, required: The summed count (installs or downloads) over this window. Unlike the HLL-based metrics, per-bucket `time_series` values sum to this total. - `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). - `time_series` PatchMetricTimeSeriesEntry[], nullable: Per-bucket series for this window, present only when a `granularity` was requested; otherwise null. On `previous`, also null when the prior window reaches past the plan's metrics-history horizon (the total is still present — only the granular overlay is withheld). Empty buckets are omitted — gap-fill against this window's `range`. - `period` string, date-time, required: The bucket start (UTC). - `count` integer, required: The summed count in this bucket. - `breakdown` PatchMetricBreakdownEntry[], nullable: Per-group counts for this window, present only when a `group_by` was requested; otherwise null. - `group_by` string, required: The dimension this entry breaks down by ("release" or "patch"). - `group_value` string, required: The value within `group_by`: the release version, or the patch number as a string. - `count` integer, required: The summed count for this group over the window. - `time_series` PatchMetricTimeSeriesEntry[], nullable: Per-bucket series for this group, present only when a `granularity` was requested; otherwise null. - `period` string, date-time, required: The bucket start (UTC). - `count` integer, required: The summed count in this bucket. - `previous` PatchMetricWindow: One window of the patch-metric envelope: the summed count over the window's effective range, with a per-bucket series when a `granularity` was requested. This base atom is the full shape of `previous`; `current` extends it (see PatchMetricCurrentWindow). - `count` integer, required: The summed count (installs or downloads) over this window. Unlike the HLL-based metrics, per-bucket `time_series` values sum to this total. - `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). - `time_series` PatchMetricTimeSeriesEntry[], nullable: Per-bucket series for this window, present only when a `granularity` was requested; otherwise null. On `previous`, also null when the prior window reaches past the plan's metrics-history horizon (the total is still present — only the granular overlay is withheld). Empty buckets are omitted — gap-fill against this window's `range`. - `period` string, date-time, required: The bucket start (UTC). - `count` integer, required: The summed count in this bucket. ## 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)