# Quota

> > This page is auto-generated from the formations OpenAPI spec.
> Do not edit manually — run `pnpm generate-formations-resource-docs` to regenerate.

# Quota

> This page is auto-generated from the formations OpenAPI spec.
> Do not edit manually — run `pnpm generate-formations-resource-docs` to regenerate.

Creates a quota — a project-scoped cap that blocks (`enforce`) or reports (`monitor`) when a windowed aggregate is exceeded. `requests` quotas are enforced by the request middleware; `tokens`/`cost_usd` quotas at the pre-generation check. Mirrors the quotas REST contract; `scope`, `metric`, `window`, and `meter_type` are immutable after creation (only `limit`, `mode`, and `on_unpriced` update).

## Syntax

```yaml
type: quota
properties:
  scope: String
  scope_ref: String
  metric: String
  window: String
  limit: Number
  mode: String
  on_unpriced: String
  meter_type: String
```

## Output

The physical resource ID is the **public ID** of the created resource. Reference it from other resources with a `ref` expression:

```yaml
      some_field:
        ref: MyQuota
```

## Properties

**`scope`**

The scope the quota applies to

_Required_: Yes
_Type_: String
_Allowed values_: `project`, `api_key`, `agent`, `actor`

---

**`scope_ref`**

Public id of the api key / agent / actor the quota applies to. For `api_key` and `agent` scope, NULL means all entities of that scope type in the project. For `actor` scope, NULL means one budget *per* actor rather than a pooled total across all actors.

_Required_: No
_Type_: String
_Nullable_: Yes

---

**`metric`**

The metric being capped

_Required_: Yes
_Type_: String
_Allowed values_: `requests`, `tokens`, `cost_usd`, `storage_bytes`

---

**`window`**

The window over which the metric is aggregated. storage_bytes caps a stored total rather than a windowed one, so it takes current and refuses every other value; current is refused for every other metric.

_Required_: Yes
_Type_: String
_Allowed values_: `rolling_1m`, `rolling_1h`, `rolling_24h`, `calendar_month`, `current`

---

**`limit`**

The cap. Positive integer for requests/tokens/storage_bytes (bytes); fractional allowed for cost_usd.

_Required_: Yes
_Type_: Number

---

**`mode`**

enforce blocks with 429; monitor fires the webhook only

_Required_: No
_Type_: String
_Allowed values_: `enforce`, `monitor`

---

**`on_unpriced`**

Only for metric cost_usd. What an enforce quota does over a pricing blackout — block (the default) refuses generations with 409 QUOTA_UNENFORCEABLE, allow accepts the unmeasurable spend. See the quotas REST contract.

_Required_: No
_Type_: String
_Allowed values_: `block`, `allow`

---

**`meter_type`**

Only for metric cost_usd. The meter this cap answers for; omit it and the cap sums every priced meter. See the quotas REST contract.

_Required_: No
_Type_: String
_Allowed values_: `llm_tokens`, `compute_execution`, `api_request`, `storage`

---