Skip to main content
If you resell NestAPI — one key per customer — a single heavy customer can consume the whole account’s nesting minutes and starve everyone else. Fairness is a second admission gate that divides your included minutes across your keys, so each customer gets a guaranteed share.
Fairness endpoints require an Admin key (or the account owner). Configuring it is a paid-plan feature, and it is off by default — until you enable it your minutes behave as a single shared pool. The usage breakdown is readable either way; while fairness is off the rows are informational only.

​
How the share is worked out

Each API key on your account is treated as one customer, and carries a weight:
  • Your included minutes are split into a reserved floor pool and a shared burst pool, in the proportion set by BurstPercent (default 10% burst, 90% floors).
  • Each key’s effective floor is weight ÷ Σ weights × floor pool — minutes genuinely reserved for it. A key always gets its floor even if every other key has drained the burst pool, and an idle key’s floor is not lent out to a greedier one.
  • Once a key is over its own floor, it may draw from the shared burst pool, first-come first-served, until that pool is exhausted.
  • Beyond floor plus whatever burst remains, the nest either spills into overage or is rejected, depending on whether overage is enabled.
Give a customer a higher weight to hand them a larger guaranteed slice. Weights are always normalised against the total, so you can’t over-allocate, and adding or removing a customer rebalances everyone’s share automatically — there is nothing to recalculate by hand.
Weight and membership changes are forward-looking: shares are recomputed from current weights and what has already been used, so a change part-way through a period reshapes floors from that point on and never claws back minutes a customer has already spent.

​
Periods

Fairness accounting follows your plan’s billing period. When the period renews, every key starts from zero — unused minutes are forfeited rather than rolled over. A nest that is still running across a renewal settles into the period it started in, so it is neither lost nor charged twice.

​
Configuration

​
Weighting one customer

Send "LineageWeight": null to clear the override and fall back to the plan default.

​
Seeing where the minutes went

GET /usage/fairness returns the current period’s breakdown — one row per key, plus the account totals (IncludedMinutes, SharedBurstMinutes, and whether fairness and overage are on).
Each row reports:
Sizing is the field to drive off when tuning: undersized means the customer keeps hitting overage and needs more weight; oversized means it chronically forfeits share it never uses.