---
title: "Get the signed-in user's patch install usage."
method: GET
path: "/usage"
tags: ["billing"]
---

# Get the signed-in user's patch install usage.

`GET /usage`

## Request

- Base URL: `https://api.shorebird.dev/api/v1`
- URL: `https://api.shorebird.dev/api/v1/usage`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Patch installs this allotment period (the base subscription's
current billing period) for every app in every organization the
signed-in user owns, and where the account stands against its
plan. Service accounts are refused with a `403`
(`service_account_forbidden`).

## Response `200`

The user's usage.

- GetUsageResponse: The response body for GET /usage and GET /organizations/{organizationId}/usage.
  - `apps` AppUsage[], required: Patch installs this allotment period for each app in every organization the account's owner owns.
    - `id` string, required: The ID of the app.
    - `name` string, required: The display name of the app.
    - `patch_install_count` integer, required: The app's patch installs this allotment period.
  - `position` AccountPosition, required: Where the account stands against its plan right now, worked out by the server so every client shows the same figures. Counts are per allotment period (the base subscription's billing period) unless said otherwise. Overage is per overage period, which for an annual plan is the month its overage subscription bills on.
    - `included_installs` integer, required: Installs the account may make this allotment period before overage begins: the plan's allotment plus any credit.
    - `installs` integer, required: Installs served so far this allotment period.
    - `included_installs_used` integer, required: Installs taken from the included allotment. Installs billed as overage are not counted here.
    - `included_exhausted` boolean, required: Whether the included allotment is used up.
    - `overage_installs` integer, required: Overage installs billed this overage period, capped at the spending limit. `0` when the plan has no overage billing.
    - `install_ceiling` integer, nullable, required: The install count at which patches stop being served, or null when nothing stops them.
    - `remaining_installs` integer, nullable, required: Installs left before `install_ceiling`, or null when there is no ceiling.
    - `at_ceiling` boolean, required: Whether `install_ceiling` has been reached.
    - `nearing_limit` boolean, required: Whether installs have reached the share of `install_ceiling` at which Shorebird emails a warning.
    - `consuming_overage` boolean, required: Whether installs are being billed as overage right now.
    - `accrued_overage_amount` string, nullable, required: What `overage_installs` costs at the plan's overage price, in minor units of the plan's currency, as a decimal number in a string because it can be fractional. Null when the plan has no overage billing.
  - `reported_overage` integer, nullable, required: Overage installs already reported to Stripe for billing this overage period. Null when the plan has no overage billing.

## Other responses

- `424`: Stripe, the database, or the install metrics could not be read (`organization_usage_get_error`).
- `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)