Quota API

Enforce usage limits in real time with microsecond-latency checks.

Check quota

POST/v1/quota/check

Ask whether a customer can consume a given amount.

json

{
  "meter_id": "01HQXYZ...",
  "customer_id": "01HQABC...",
  "requested_amount": 1.0,
  "idempotency_key": "check_001"
}

Response

json

{
  "allowed": true,
  "current_usage": 4200.0,
  "limit": 5000.0,
  "remaining": 800.0,
  "enforcement": "hard_cap"
}

Batch check

POST/v1/quota/check-multi

Check multiple quotas in a single request. Supports all_or_nothing mode.

json

{
  "checks": [
    { "meter_id": "...", "customer_id": "...", "requested_amount": 1.0 },
    { "meter_id": "...", "customer_id": "...", "requested_amount": 5.0 }
  ],
  "all_or_nothing": true
}

Enforcement modes

hard_cap blocks requests that would exceed the limit. soft_cap allows them but flags the overage for billing.

Quota snapshot

GET/v1/quota/snapshot?customer=...

Get a snapshot of all quota states for a customer.

Response

json

[
  {
    "meter_id": "01HQXYZ...",
    "meter_slug": "api-requests",
    "current_usage": 4200.0,
    "limit": 5000.0,
    "remaining": 800.0,
    "percent_used": 84.0,
    "reset_period": "monthly",
    "enforcement": "hard_cap"
  }
]

Two-phase commit

For workflows that need to guarantee capacity before performing an action.

1. Reserve

POST/v1/quota/reserve

json

{ "meter_id": "01HQXYZ...", "customer_id": "01HQABC...", "amount": 10.0 }

Response

json

{
  "reservation_id": "res_01HQ...",
  "expires_at": "2026-03-19T12:05:00Z"
}

Reservations expire after 5 minutes. Commit or release before then to finalize.

2. Commit or release

POST/v1/quota/reservations/:id/commit

POST/v1/quota/reservations/:id/release

Commit deducts from the quota permanently. Release returns the reserved capacity.

Commit response

json

{ "committed": true, "reservation_id": "res_01HQ..." }

Release response

json

{ "released": true, "reservation_id": "res_01HQ..." }

Set quota limits

PUT/v1/quota/limits/:meter_slug/customers/:customer_external_id

Field	Type	Required	Description
`limit`	number	Yes	The usage limit value
`reset_period`	string	Yes	"monthly" \| "daily" \| "yearly" \| "never"
`enforcement`	string	Yes	"hard_cap" \| "soft_cap"

json

{ "limit": 10000.0, "reset_period": "monthly", "enforcement": "hard_cap" }

Override precedence

When evaluating limits, Meterd applies the first match in this order: Customer-specific override > Plan-feature limit > Feature default.

Remove quota override

DELETE/v1/quota/limits/:meter_slug/customers/:customer_external_id

Remove a customer-specific quota override. After removal the customer falls back to the plan-level or feature-default limit.

Performance

Quota checks are designed for microsecond-latency responses with built-in redundancy to ensure high availability.