Usage, limits, and billing

Every Chainguard Starter and Chainguard Team organization has 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:

chainctl plans describe

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

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:

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:

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. On Team, contact Chainguard 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.
• 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.