Manage Quotas

Prerequisites

Review the Quotas concept page and the Quota reference.
Have the org-level view permission for the org whose quotas you are managing. (Browsing the quota catalog requires only a valid token, since it is not org-specific.)
An authorization token (see Authentication).

Authentication

The quota endpoints are served from https://billing-ng.cpln.io and use the same Bearer token authentication as the rest of the Control Plane API. Obtain a token using either method:

Service account key — create a service account with the necessary permissions and generate a key.
User access token — log in with cpln login, then run cpln profile token <profile-name>.

Include the token in the Authorization header of every request:

Authorization: Bearer YOUR_TOKEN_HERE

In the examples below, replace YOUR_TOKEN_HERE with your token and my-org with your org name.

View Your Current Quotas

List every quota on your org, including its current usage and allowed maximum:

curl --request GET \
  --url https://billing-ng.cpln.io/org/my-org/quotas \
  --header 'Authorization: Bearer YOUR_TOKEN_HERE'

The response is an array of quotas:

[
  {
    "id": "5d2c0a1e-7b3f-4d8a-9c11-2f6e8b4a1c90",
    "name": "workloads-per-gvc",
    "description": "Maximum number of workloads in a GVC",
    "unit": "count",
    "max": 50,
    "current": 32,
    "origin": "default"
  }
]

Field	Description
`id`	Unique identifier of the quota. Used when correlating an increase.
`name`	The quota name. Use this value as `quotaName` when requesting an increase.
`description`	Human-readable description of the resource the quota limits.
`unit`	The unit the quota is measured in.
`max`	The highest value your org is allowed to reach.
`current`	The org’s current usage of the resource.
`origin`	Where the limit comes from — `default` (the standard limit) or `builtin`.

Browse the Quota Catalog

The catalog lists every quota that can exist, with its unit and description. Use it to find the exact quotaName to request an increase for:

curl --request GET \
  --url https://billing-ng.cpln.io/quota_catalog \
  --header 'Authorization: Bearer YOUR_TOKEN_HERE'

[
  {
    "name": "workloads-per-gvc",
    "unit": "count",
    "description": "Maximum number of workloads in a GVC",
    "defaultMax": 50
  }
]

Request a Quota Increase

Submit a request for a single quota and the new max you want. Provide the quotaName (from your current quotas or the catalog) and a requestedMax:

curl --request POST \
  --url https://billing-ng.cpln.io/org/my-org/quota-increase-requests \
  --header 'Authorization: Bearer YOUR_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "quotaName": "workloads-per-gvc",
    "requestedMax": 100
  }'

The response is the created request, including its id and status:

{
  "id": "a1b2c3d4-e5f6-47a8-9b0c-1d2e3f4a5b6c",
  "org": "my-org",
  "quotaName": "workloads-per-gvc",
  "requestedMax": 100,
  "status": "approved",
  "autoApproved": true,
  "createdBy": "user@example.com",
  "created": "2026-06-30T15:04:05Z",
  "resolvedBy": "system",
  "resolved": "2026-06-30T15:04:05Z"
}

The status tells you what happened:

approved — the increase was granted. When autoApproved is true, it was granted automatically and the new max is applied to your org shortly after. A resolvedBy of system indicates an automatic approval.
pending — the request was larger than can be granted automatically and is awaiting review by the Control Plane team. Note the returned id so you can check its status later.

A quota increase request only ever raises a limit. A request for a value at or below your current max is treated as already satisfied and leaves the quota unchanged.

Check the Status of a Request

Retrieve a request by its id to see its current status:

curl --request GET \
  --url https://billing-ng.cpln.io/quota-increase-requests/a1b2c3d4-e5f6-47a8-9b0c-1d2e3f4a5b6c \
  --header 'Authorization: Bearer YOUR_TOKEN_HERE'

{
  "id": "a1b2c3d4-e5f6-47a8-9b0c-1d2e3f4a5b6c",
  "org": "my-org",
  "quotaName": "workloads-per-gvc",
  "requestedMax": 100,
  "status": "approved",
  "autoApproved": false,
  "createdBy": "user@example.com",
  "created": "2026-06-30T15:04:05Z",
  "resolvedBy": "ops@controlplane.com",
  "resolved": "2026-06-30T17:22:41Z"
}

A pending request becomes approved or denied once it has been reviewed. After a request is approved, the new max appears on the quota when you view your current quotas.

List Your Org’s Requests

To see all increase requests for your org, list them with the org query parameter. Add an optional status filter (pending, approved, or denied):

curl --request GET \
  --url 'https://billing-ng.cpln.io/quota-increase-requests?org=my-org&status=pending' \
  --header 'Authorization: Bearer YOUR_TOKEN_HERE'

The response is an array of the requests for your org.

Next Steps

Learn how quotas and increase requests work in the Quotas concept page.
See the Quota reference for the list of quota resources and their permissions.

How-to Guides

CLI Configuration

Integrations

Configure Resources

Create Resources

Deployment

GitOps

Images

Native Networking

Observability

Sandbox

Workload Access

Prerequisites

Authentication

View Your Current Quotas

Browse the Quota Catalog

Request a Quota Increase

Check the Status of a Request

List Your Org’s Requests

Next Steps

​Prerequisites

​Authentication

​View Your Current Quotas

​Browse the Quota Catalog

​Request a Quota Increase

​Check the Status of a Request

​List Your Org’s Requests

​Next Steps

Prerequisites

Authentication

View Your Current Quotas

Browse the Quota Catalog

Request a Quota Increase

Check the Status of a Request

List Your Org’s Requests

Next Steps