API reference

QuotaService

api.plany.cloud:443Global8 methods

See your limits and how much of each you are using, and ask for more. Quotas cap how many servers, vCPUs, secrets, projects and so on an account or project can hold, with defaults set by your plan. When you need a higher limit, file a quota increase request: many are approved automatically in moments, and the rest are decided by a person at Plany.

GetQuotaLimit

Read

plany.quota.v1.QuotaService/GetQuotaLimit

Parameters

namestringRequired

Returns

QuotaLimit.

1grpcurl -H "authorization: Bearer $PLANY_API_KEY" \
2  -d '{
3    "name": "accounts//quotaLimits/my-quota-limit"
4  }' \
5  api.plany.cloud:443 plany.quota.v1.QuotaService/GetQuotaLimit

Example response

1{
2  "name": "accounts//quotaLimits/my-quota-limit",
3  "metric": "quotaMetrics/my-quota-metric",
4  "location": "",
5  "effective_limit": "0",
6  "default_limit": "0",
7  "current_usage": "0",
8  "pending_usage": "0",
9  "unit": "",
10  "limit_type": "LIMIT_TYPE_CONCURRENT",
11  "reset_time": "2026-10-04T12:00:00Z"
12}

ListQuotaLimits

Read

plany.quota.v1.QuotaService/ListQuotaLimits

Lists limits and live usage for a consumer. Backs the console's quota page and the plany quota list command.

Parameters

parentstringRequired
accounts/{account} or projects/{project}.
locationstring
Restrict to one location.
servicestring
Restrict to the metrics of one product, e.g. secretmanager.plany.cloud.
page_sizeint32
page_tokenstring

Returns

ListQuotaLimitsResponse.

1grpcurl -H "authorization: Bearer $PLANY_API_KEY" \
2  -d '{
3    "parent": "",
4    "page_size": 50
5  }' \
6  api.plany.cloud:443 plany.quota.v1.QuotaService/ListQuotaLimits

Example response

1{
2  "quota_limits": [
3    {
4      "name": "accounts//quotaLimits/my-quota-limit",
5      "metric": "quotaMetrics/my-quota-metric",
6      "location": "",
7      "effective_limit": "0",
8      "default_limit": "0",
9      "current_usage": "0",
10      "pending_usage": "0",
11      "unit": "",
12      "limit_type": "LIMIT_TYPE_CONCURRENT",
13      "reset_time": "2026-10-04T12:00:00Z"
14    }
15  ],
16  "next_page_token": ""
17}

ListQuotaMetrics

Read

plany.quota.v1.QuotaService/ListQuotaMetrics

Parameters

servicestring
page_sizeint32
page_tokenstring

Returns

ListQuotaMetricsResponse.

1grpcurl -H "authorization: Bearer $PLANY_API_KEY" \
2  -d '{
3    "page_size": 50
4  }' \
5  api.plany.cloud:443 plany.quota.v1.QuotaService/ListQuotaMetrics

Example response

1{
2  "quota_metrics": [
3    {
4      "name": "quotaMetrics/my-quota-metric",
5      "display_name": "My server",
6      "description": "",
7      "service": "",
8      "limit_type": "LIMIT_TYPE_CONCURRENT",
9      "scope": "SCOPE_ACCOUNT",
10      "unit": "",
11      "rate_window": "300s",
12      "plan_defaults": {
13        "key": "0"
14      },
15      "auto_approve_max": {
16        "key": "0"
17      }
18    }
19  ],
20  "next_page_token": ""
21}

ListQuotaOverrides

Read

plany.quota.v1.QuotaService/ListQuotaOverrides

Parameters

parentstringRequired
page_sizeint32
page_tokenstring

Returns

ListQuotaOverridesResponse.

1grpcurl -H "authorization: Bearer $PLANY_API_KEY" \
2  -d '{
3    "parent": "",
4    "page_size": 50
5  }' \
6  api.plany.cloud:443 plany.quota.v1.QuotaService/ListQuotaOverrides

Example response

1{
2  "quota_overrides": [
3    {
4      "name": "accounts//quotaOverrides/my-quota-override",
5      "metric": "quotaMetrics/my-quota-metric",
6      "location": "",
7      "limit": "0",
8      "reason": "",
9      "granted_by": "",
10      "create_time": "2026-10-04T12:00:00Z",
11      "expire_time": "2026-10-04T12:00:00Z"
12    }
13  ],
14  "next_page_token": ""
15}

CreateQuotaIncreaseRequest

plany.quota.v1.QuotaService/CreateQuotaIncreaseRequest

Asks for a limit to go up.

The request is assessed straight away. If the metric can be raised automatically for your plan and the new limit is within that ceiling, it is granted at once; otherwise it waits for a person at Plany to decide.

Every metric may be asked about.

Parameters

parentstringRequired
accounts/{account} or projects/{project}.
quota_increase_requestQuotaIncreaseRequestRequired
Show child attributesHide child attributes
- metricstringRequired
- requested_limitint64Required
  The ceiling being asked for. An absolute limit, not a delta — a customer knows how many servers they want to run, not how many more.
- namestringIdentifier
- locationstring
  Location asked about. Empty means every location, matching QuotaOverride.
- justificationstring
  Why you need it, in your own words. Optional — most requests are settled automatically and nobody needs to read it.
  
  Blank is accepted; a few characters are not. When a person does decide, a real sentence is what helps them.

Returns

QuotaIncreaseRequest.

1grpcurl -H "authorization: Bearer $PLANY_API_KEY" \
2  -d '{
3    "parent": "",
4    "quota_increase_request": {
5      "metric": "quotaMetrics/my-quota-metric",
6      "requested_limit": "0"
7    }
8  }' \
9  api.plany.cloud:443 plany.quota.v1.QuotaService/CreateQuotaIncreaseRequest

Example response

1{
2  "name": "accounts//quotaIncreaseRequests/my-quota-increase-request",
3  "consumer": "",
4  "metric": "quotaMetrics/my-quota-metric",
5  "location": "",
6  "requested_limit": "0",
7  "current_limit": "0",
8  "default_limit": "0",
9  "unit": "",
10  "justification": "",
11  "state": "STATE_PENDING",
12  "decision": "DECISION_AUTOMATIC",
13  "granted_limit": "0",
14  "decision_reason": "",
15  "decided_by": "",
16  "requested_by": "",
17  "create_time": "2026-10-04T12:00:00Z",
18  "decide_time": "2026-10-04T12:00:00Z",
19  "expire_time": "2026-10-04T12:00:00Z",
20  "quota_override": "accounts//quotaOverrides/my-quota-override"
21}

GetQuotaIncreaseRequest

Read

plany.quota.v1.QuotaService/GetQuotaIncreaseRequest

Parameters

namestringRequired

Returns

QuotaIncreaseRequest.

1grpcurl -H "authorization: Bearer $PLANY_API_KEY" \
2  -d '{
3    "name": "accounts//quotaIncreaseRequests/my-quota-increase-request"
4  }' \
5  api.plany.cloud:443 plany.quota.v1.QuotaService/GetQuotaIncreaseRequest

Example response

1{
2  "name": "accounts//quotaIncreaseRequests/my-quota-increase-request",
3  "consumer": "",
4  "metric": "quotaMetrics/my-quota-metric",
5  "location": "",
6  "requested_limit": "0",
7  "current_limit": "0",
8  "default_limit": "0",
9  "unit": "",
10  "justification": "",
11  "state": "STATE_PENDING",
12  "decision": "DECISION_AUTOMATIC",
13  "granted_limit": "0",
14  "decision_reason": "",
15  "decided_by": "",
16  "requested_by": "",
17  "create_time": "2026-10-04T12:00:00Z",
18  "decide_time": "2026-10-04T12:00:00Z",
19  "expire_time": "2026-10-04T12:00:00Z",
20  "quota_override": "accounts//quotaOverrides/my-quota-override"
21}

ListQuotaIncreaseRequests

Read

plany.quota.v1.QuotaService/ListQuotaIncreaseRequests

Lists your requests, for an account or a project.

Parameters

parentstringRequired
The account or project whose requests to list.
stateQuotaIncreaseRequest.State
Restrict to one state. Unspecified returns every state, newest first — which is the customer's view of their own history. The queue asks for STATE_PENDING.

STATE_PENDINGSTATE_APPROVEDSTATE_DENIEDSTATE_WITHDRAWN
page_sizeint32
page_tokenstring

Returns

ListQuotaIncreaseRequestsResponse.

1grpcurl -H "authorization: Bearer $PLANY_API_KEY" \
2  -d '{
3    "parent": "",
4    "page_size": 50
5  }' \
6  api.plany.cloud:443 plany.quota.v1.QuotaService/ListQuotaIncreaseRequests

Example response

1{
2  "quota_increase_requests": [
3    {
4      "name": "accounts//quotaIncreaseRequests/my-quota-increase-request",
5      "consumer": "",
6      "metric": "quotaMetrics/my-quota-metric",
7      "location": "",
8      "requested_limit": "0",
9      "current_limit": "0",
10      "default_limit": "0",
11      "unit": "",
12      "justification": "",
13      "state": "STATE_PENDING",
14      "decision": "DECISION_AUTOMATIC",
15      "granted_limit": "0",
16      "decision_reason": "",
17      "decided_by": "",
18      "requested_by": "",
19      "create_time": "2026-10-04T12:00:00Z",
20      "decide_time": "2026-10-04T12:00:00Z",
21      "expire_time": "2026-10-04T12:00:00Z",
22      "quota_override": "accounts//quotaOverrides/my-quota-override"
23    }
24  ],
25  "next_page_token": "",
26  "pending_count": 0
27}

WithdrawQuotaIncreaseRequest

plany.quota.v1.QuotaService/WithdrawQuotaIncreaseRequest

Takes back a request before anybody has acted on it.

A customer's own, so a mistyped number does not have to occupy somebody's queue until they refuse it. Refused once decided: withdrawing an approved request would imply the override went with it, and it does not.

Parameters

namestringRequired

Returns

QuotaIncreaseRequest.

1grpcurl -H "authorization: Bearer $PLANY_API_KEY" \
2  -d '{
3    "name": "accounts//quotaIncreaseRequests/my-quota-increase-request"
4  }' \
5  api.plany.cloud:443 plany.quota.v1.QuotaService/WithdrawQuotaIncreaseRequest

Example response

1{
2  "name": "accounts//quotaIncreaseRequests/my-quota-increase-request",
3  "consumer": "",
4  "metric": "quotaMetrics/my-quota-metric",
5  "location": "",
6  "requested_limit": "0",
7  "current_limit": "0",
8  "default_limit": "0",
9  "unit": "",
10  "justification": "",
11  "state": "STATE_PENDING",
12  "decision": "DECISION_AUTOMATIC",
13  "granted_limit": "0",
14  "decision_reason": "",
15  "decided_by": "",
16  "requested_by": "",
17  "create_time": "2026-10-04T12:00:00Z",
18  "decide_time": "2026-10-04T12:00:00Z",
19  "expire_time": "2026-10-04T12:00:00Z",
20  "quota_override": "accounts//quotaOverrides/my-quota-override"
21}

The QuotaMetric object

quotaMetrics/{{quota_metric}}

QuotaMetric describes something that can be limited.

Metric names are namespaced by the product that owns them, e.g. microvm.plany.cloud/instances or secretmanager.plany.cloud/secrets.

Attributes

namestringIdentifier
quotaMetrics/{quota_metric} where the id is the namespaced metric name.
display_namestringOutput only
descriptionstringOutput only
servicestringOutput only
The product that owns this metric, e.g. secretmanager.plany.cloud.
limit_typeLimitTypeOutput only
LIMIT_TYPE_CONCURRENTLIMIT_TYPE_RATE
scopeQuotaMetric.ScopeOutput only
SCOPE_ACCOUNTSCOPE_PROJECTSCOPE_PROJECT_LOCATIONSCOPE_ACCOUNT_LOCATION
unitstringOutput only
Unit the limit is counted in: "instances", "vcpus", "bytes", "requests".
rate_windowDurationOutput only
Window for a RATE metric. Ignored for CONCURRENT.
plan_defaultsmap<string, int64>Output only
Default limit by plan id, e.g. {"hobby": 2, "pro": 20}. The starting point before any override is applied.
auto_approve_maxmap<string, int64>Output only
Highest limit that can be granted automatically, by plan id.

A metric with no entry for your plan can still be requested; a person at Plany decides it. It caps the resulting limit, not the size of each step, so repeated requests stop at this number.

QuotaMetric

1{
2  "name": "quotaMetrics/my-quota-metric",
3  "display_name": "My server",
4  "description": "",
5  "service": "",
6  "limit_type": "LIMIT_TYPE_CONCURRENT",
7  "scope": "SCOPE_ACCOUNT",
8  "unit": "",
9  "rate_window": "300s",
10  "plan_defaults": {
11    "key": "0"
12  },
13  "auto_approve_max": {
14    "key": "0"
15  }
16}

The QuotaOverride object

accounts//quotaOverrides/{{quota_override}}

QuotaOverride raises or lowers a limit for one consumer.

Attributes

metricstringRequired
limitint64Required
namestringIdentifier
locationstring
Location the override applies in. Empty means every location.
reasonstring
Why it was granted.
granted_bystringOutput only
Principal that granted it.
create_timeTimestampOutput only
expire_timeTimestamp
When the override lapses and the plan default returns. Empty means permanent. Temporary grants are the right tool for a launch weekend.

QuotaOverride

1{
2  "name": "accounts//quotaOverrides/my-quota-override",
3  "metric": "quotaMetrics/my-quota-metric",
4  "location": "",
5  "limit": "0",
6  "reason": "",
7  "granted_by": "",
8  "create_time": "2026-10-04T12:00:00Z",
9  "expire_time": "2026-10-04T12:00:00Z"
10}

ListQuotaIncreaseRequestsResponse

quota_increase_requestsrepeated QuotaIncreaseRequest
Show child attributesHide child attributes
- metricstringRequired
- requested_limitint64Required
  The ceiling being asked for. An absolute limit, not a delta — a customer knows how many servers they want to run, not how many more.
- namestringIdentifier
- consumerstringOutput only
  accounts/{account} or projects/{project} — whose limit this is about. Redundant with the name's prefix and carried anyway, because every read path here filters on it and parsing a name to filter is how a wildcard listing acquires a bug.
- locationstring
  Location asked about. Empty means every location, matching QuotaOverride.
- current_limitint64Output only
  What the limit was when the request was made, and what the plan gives. Recorded at the time rather than read live, so the request still makes sense after the limit moves.
- default_limitint64Output only
- unitstringOutput only
- justificationstring
  Why you need it, in your own words. Optional — most requests are settled automatically and nobody needs to read it.
  
  Blank is accepted; a few characters are not. When a person does decide, a real sentence is what helps them.
- stateQuotaIncreaseRequest.StateOutput only
  STATE_PENDINGSTATE_APPROVEDSTATE_DENIEDSTATE_WITHDRAWN
- decisionQuotaIncreaseRequest.DecisionOutput only
  DECISION_AUTOMATICDECISION_MANUAL
- granted_limitint64Output only
  What was actually granted. May be below requested_limit: a partial grant is a real outcome and both the console and the email say so rather than implying the whole ask was met.
- decision_reasonstringOutput only
  The reviewer's sentence, shown to you verbatim. Always present on a refusal, so you know what to do next.
- decided_bystringOutput only
  Principal that decided, or empty for an automatic decision.
- requested_bystringOutput only
  Principal that asked.
- create_timeTimestampOutput only
- decide_timeTimestampOutput only
- expire_timeTimestampOutput only
  When the granted override lapses. Empty means permanent, which is what an automatic approval always is — granting for a week and reverting silently is the "why did our limit go back down" problem, deliberately created.
- quota_overridestringOutput only
  The override this request produced, .../quotaOverrides/{override}. Empty until approved. Written in the same transaction as the state change, so an approved request without an override is not a state this can be in.
next_page_tokenstring
pending_countint32
How many are still waiting on somebody, across the whole queue and regardless of the page or the state filter. What a console puts in a badge.

ListQuotaLimitsResponse

quota_limitsrepeated QuotaLimit
Show child attributesHide child attributes
- namestringIdentifier
- metricstringOutput only
  Metric this limits, quotaMetrics/{quota_metric}.
- locationstringOutput only
  Location this limit applies in, for location-scoped metrics. Empty for metrics counted globally.
- effective_limitint64Output only
  Limit in force: the plan default unless an override supersedes it.
- default_limitint64Output only
  The plan default, retained so a UI can show what an override changed.
- current_usageint64Output only
  Units currently held (CONCURRENT) or consumed in the window (RATE).
- pending_usageint64Output only
  Units allocated but not yet confirmed in use — reservations held by in-flight creates. Counted against the limit so two concurrent creates cannot both pass a check that only one of them fits through.
- unitstringOutput only
- limit_typeLimitTypeOutput only
  LIMIT_TYPE_CONCURRENTLIMIT_TYPE_RATE
- reset_timeTimestampOutput only
  For a RATE metric, when the window resets.
next_page_tokenstring

ListQuotaMetricsResponse

quota_metricsrepeated QuotaMetric
Show child attributesHide child attributes
- namestringIdentifier
  quotaMetrics/{quota_metric} where the id is the namespaced metric name.
- display_namestringOutput only
- descriptionstringOutput only
- servicestringOutput only
  The product that owns this metric, e.g. secretmanager.plany.cloud.
- limit_typeLimitTypeOutput only
  LIMIT_TYPE_CONCURRENTLIMIT_TYPE_RATE
- scopeQuotaMetric.ScopeOutput only
  SCOPE_ACCOUNTSCOPE_PROJECTSCOPE_PROJECT_LOCATIONSCOPE_ACCOUNT_LOCATION
- unitstringOutput only
  Unit the limit is counted in: "instances", "vcpus", "bytes", "requests".
- rate_windowDurationOutput only
  Window for a RATE metric. Ignored for CONCURRENT.
- plan_defaultsmap<string, int64>Output only
  Default limit by plan id, e.g. {"hobby": 2, "pro": 20}. The starting point before any override is applied.
- auto_approve_maxmap<string, int64>Output only
  Highest limit that can be granted automatically, by plan id.
  
  A metric with no entry for your plan can still be requested; a person at Plany decides it. It caps the resulting limit, not the size of each step, so repeated requests stop at this number.
next_page_tokenstring

ListQuotaOverridesResponse

quota_overridesrepeated QuotaOverride
Show child attributesHide child attributes
- metricstringRequired
- limitint64Required
- namestringIdentifier
- locationstring
  Location the override applies in. Empty means every location.
- reasonstring
  Why it was granted.
- granted_bystringOutput only
  Principal that granted it.
- create_timeTimestampOutput only
- expire_timeTimestamp
  When the override lapses and the plan default returns. Empty means permanent. Temporary grants are the right tool for a launch weekend.
next_page_tokenstring

QuotaIncreaseRequest

QuotaIncreaseRequest is you asking for a limit to go up.

Automatic approval only ever approves. It has two outcomes, "granted" and "a person decides", and never refuses. Only a person at Plany can refuse a request, and a refusal always carries their own reason.

So every request ends in one of three ways: approved automatically, approved by a person, or refused by a person.

metricstringRequired
requested_limitint64Required
The ceiling being asked for. An absolute limit, not a delta — a customer knows how many servers they want to run, not how many more.
namestringIdentifier
consumerstringOutput only
accounts/{account} or projects/{project} — whose limit this is about. Redundant with the name's prefix and carried anyway, because every read path here filters on it and parsing a name to filter is how a wildcard listing acquires a bug.
locationstring
Location asked about. Empty means every location, matching QuotaOverride.
current_limitint64Output only
What the limit was when the request was made, and what the plan gives. Recorded at the time rather than read live, so the request still makes sense after the limit moves.
default_limitint64Output only
unitstringOutput only
justificationstring
Why you need it, in your own words. Optional — most requests are settled automatically and nobody needs to read it.

Blank is accepted; a few characters are not. When a person does decide, a real sentence is what helps them.
stateQuotaIncreaseRequest.StateOutput only
STATE_PENDINGSTATE_APPROVEDSTATE_DENIEDSTATE_WITHDRAWN
decisionQuotaIncreaseRequest.DecisionOutput only
DECISION_AUTOMATICDECISION_MANUAL
granted_limitint64Output only
What was actually granted. May be below requested_limit: a partial grant is a real outcome and both the console and the email say so rather than implying the whole ask was met.
decision_reasonstringOutput only
The reviewer's sentence, shown to you verbatim. Always present on a refusal, so you know what to do next.
decided_bystringOutput only
Principal that decided, or empty for an automatic decision.
requested_bystringOutput only
Principal that asked.
create_timeTimestampOutput only
decide_timeTimestampOutput only
expire_timeTimestampOutput only
When the granted override lapses. Empty means permanent, which is what an automatic approval always is — granting for a week and reverting silently is the "why did our limit go back down" problem, deliberately created.
quota_overridestringOutput only
The override this request produced, .../quotaOverrides/{override}. Empty until approved. Written in the same transaction as the state change, so an approved request without an override is not a state this can be in.

QuotaLimit

QuotaLimit is the effective limit and current usage for one metric against one consumer.

namestringIdentifier
metricstringOutput only
Metric this limits, quotaMetrics/{quota_metric}.
locationstringOutput only
Location this limit applies in, for location-scoped metrics. Empty for metrics counted globally.
effective_limitint64Output only
Limit in force: the plan default unless an override supersedes it.
default_limitint64Output only
The plan default, retained so a UI can show what an override changed.
current_usageint64Output only
Units currently held (CONCURRENT) or consumed in the window (RATE).
pending_usageint64Output only
Units allocated but not yet confirmed in use — reservations held by in-flight creates. Counted against the limit so two concurrent creates cannot both pass a check that only one of them fits through.
unitstringOutput only
limit_typeLimitTypeOutput only
LIMIT_TYPE_CONCURRENTLIMIT_TYPE_RATE
reset_timeTimestampOutput only
For a RATE metric, when the window resets.

Enums

LimitType

LimitType distinguishes the two enforcement models.

Value	Description
LIMIT_TYPE_UNSPECIFIED
LIMIT_TYPE_CONCURRENT	A ceiling on simultaneously held units. Consumers must call AllocateQuota before creating and ReleaseQuota after destroying.
LIMIT_TYPE_RATE	A ceiling on units consumed per rolling window. Consumers call CheckQuota, which both tests and increments.

QuotaIncreaseRequest.Decision

Who decided: automatically, or a person. The outcome is the same either way.

Value	Description
DECISION_UNSPECIFIED
DECISION_AUTOMATIC	The approval policy, with no person involved.
DECISION_MANUAL	A person at Plany.

QuotaIncreaseRequest.State

Value	Description
STATE_UNSPECIFIED
STATE_PENDING	Waiting for a person at Plany to decide.
STATE_APPROVED	Granted, and the override in `quota_override` is in force. Reached either by policy or by a person; `decision` says which.
STATE_DENIED	Refused, with a reason. Only ever set by a person.
STATE_WITHDRAWN	Taken back by the customer before anybody acted on it.

QuotaMetric.Scope

Level a metric is enforced at.

Value	Description
SCOPE_UNSPECIFIED
SCOPE_ACCOUNT	Counted across the whole account, all projects and regions. Used for things an account owns rather than a project — projects themselves, members, API keys.
SCOPE_PROJECT	Counted per project, summed across regions.
SCOPE_PROJECT_LOCATION	Counted per project per region. The common case for compute: 32 vCPUs in eu-west-2 does not constrain us-east-1.
SCOPE_ACCOUNT_LOCATION	Counted per account per region.