# Usage, limits, and billing

URL: https://www.chainguard.dev/docs/get-started/self-serve/usage-and-billing.md
Last Modified: November 10, 2026
Tags: Procedural

Check your Chainguard Starter or Chainguard Team organization's usage against its plan limits, and respond to a refused request


Every Chainguard Starter and Chainguard Team organization has [plan limits](/get-started/self-serve/plans/#plan-limits). This page covers checking your usage against them, what to do when a request is refused, and what Chainguard charges you for.

## Check your usage

To see your organization's plan, the products it can use, and any limits it's close to, run `chainctl plans describe`:

```shell
chainctl plans describe
```

To list every limit with its current usage, run `chainctl plans quotas list`:

```shell
chainctl plans quotas list
```

The following options narrow the list:

* `--near` shows only the limits you're close to or have reached.
* `--product` shows only the products you name, separated by commas, such as `images`, `libraries`, `checks`, `workspaces`, and `platform`.
* `--parent` names the organization to check, if you belong to more than one.

Usage figures include anything above an included amount. On Team, storage shows as unlimited, because storage past the included 500 GiB is metered, not refused. Image egress is shown in bytes. If Chainguard can't measure a figure yet, the list shows a dash; for a new organization, that's usually the case until Chainguard's next hourly usage count. Both commands accept `--output json`.

On Starter, the rows for application, base, and AI images each show a limit of 5, but those images share one total of 5, which the catalog images row shows.

### Check usage from a script

Chainguard doesn't send you alerts as you approach a limit. To watch for limits from a scheduled job, run `chainctl plans quotas list` with `--near` and `--output json`, and read the JSON:

```shell
chainctl plans quotas list --near --output json
```

Don't rely on the exit status alone. Both `plans` commands exit with status 1 when usage is unavailable, even if `--near` shows no rows. With usage available, an empty `--near` list exits with status 0, which means no limit is near.

## When a request is refused

When a request would go past a plan limit, Chainguard refuses it and returns an error that names your plan and the limit, and what you've used or what you asked for. `chainctl` follows it with the `chainctl plans quotas list` command that shows the related limits. For example, the error message for a cooldown outside Team's range reads as follows:

```output
Team plan allows a library cooldown of 0 to 7 days (14 days requested). Upgrade: https://www.chainguard.dev/pricing or run: chainctl plans update --plan enterprise
```

To respond to a refusal, do one of the following:

* **Stay within the limit.** For example, if you're at the pull-token limit, revoke a token you no longer use before you create another one.
* **Wait for the monthly reset.** Monthly limits, such as image egress and package pulls, reset at the start of each calendar month, in UTC.
* **Upgrade.** On Starter, [upgrade to Chainguard Team](/get-started/self-serve/upgrade-team/). On Team, [contact Chainguard](https://www.chainguard.dev/contact) about an Enterprise plan.

A refusal stops only the next request. Work that's already running, such as an image pull, finishes.

## What Chainguard charges for

Chainguard charges the following to the card you save:

* **The Team plan fee**, monthly in advance. Refer to [How Team is billed](/get-started/self-serve/upgrade-team/#how-team-is-billed).
* **Storage above Team's included 500 GiB**, starting January 1, 2027.

Starter is free. Applicable tax is added to every charge. For prices, refer to the [Chainguard pricing page](https://www.chainguard.dev/pricing).