How do you set a GraphQL cost budget and allocate points across callers?

## A point has to mean something Complexity points are invented units, and an invented unit with no anchor produces theatre: a budget of "1000" that nobody can defend, tuned upward every time somebody complains. The first decision is the exchange rate, and there are only two honest choices. **One point ≈ one object fetched.** Easy to explain, easy for a client to predict from its own document, and blind to the fact that some objects are 400× more expensive than others — which you then correct with per-field weights. **One point ≈ one millisecond of measured service time.** Truer to capacity, much harder for a client to predict, and it needs continuous recalibration as the backend changes underneath it. Most teams pick the first and lean on weights. What matters is that you can finish the sentence "this endpoint can serve about N points per second" with a number derived from a load test, because that sentence is what turns a budget from a guess into capacity planning. ## Measure before you enforce Never launch a cost limiter enforcing. Run it in observe mode — compute the score, log it with the operation name and the caller, reject nothing — for long enough to cover a weekly cycle and a month-end. What you want out of that bake is the score distribution *per caller*, not a single average. The per-request cap belongs comfortably above the p99 of legitimate traffic, with headroom for the documents your own clients will write next quarter. Publish the resulting number and the weight table; a limit callers cannot predict is a limit they will trip. ## One limit is never enough A per-request cap stops the single catastrophic document. It does nothing about volume. A caller refused one 300,000-point document will send forty at 8,000, and your endpoint is just as loaded. So the second control is a **points-per-window budget per caller** — a refilling allowance, charged per operation, rather than a request counter. This is the change of unit that matters: on a REST API requests-per-minute is a rough proxy for load because routes have bounded shapes; on one GraphQL endpoint it is nearly meaningless, because two requests to the same URL can differ by five orders of magnitude. Billing in points also removes the perverse incentive to fragment: splitting one document into ten costs the same points, so clients stop gaming the shape. A refinement worth knowing: because the score is an upper bound, you can charge the estimate on admission and **refund the difference** once the actual work is known — the caller who asked for 288 readings and received 50 gets most of the points back. It makes budgets far more usable for honest clients at the price of a reconciliation path. It is a design, not a specified behaviour. ## Tiering, and treating the budget as a product surface Different callers deserve different allowances, and pretending otherwise either strangles your own app or hands an anonymous caller the same power as it: - **First-party clients** — documents you can inspect and measure ahead of shipping, so generous budgets with a pre-release check are reasonable. - **Contracted partners** — a budget that is part of the agreement, sized from their real workload and visible to them. - **Anonymous or trial traffic** — tight, and tight is defensible if the failure is informative. Whatever the tier, the rejection has to be actionable. Returning the score, the budget and the largest contributing path, and documenting the weights, is the difference between an integrator fixing their document in ten minutes and filing a ticket. That is a product decision as much as a security one. ## The organisational problem In a supergraph composed from 62 subgraphs, nobody has a global view of what a field costs. The team that resolves a field knows its cost; the platform team owns the budget and the blast radius. The workable split is that the owning team proposes a field's weight, the platform reviews it in the same change as the schema, and new fields land on a conservative default rather than a free one. Without that review, weights drift toward zero — every team's own field feels cheap — and the budget quietly stops binding. Two habits keep it honest: a periodic recalibration comparing configured weights against measured per-field cost on real traffic, and treating a weight change as a compatibility event, because raising a weight can invalidate documents that clients have already shipped. ## What you are trading away Static scoring over-charges by construction, so a budget tight enough to stop abuse will refuse some legitimate documents; that is the trade, and the mitigation is calibration and per-caller budgets, not a bigger global number. Over-restriction has its own cost: integrators fragment their traffic, poll more often and cache worse, so you push load around rather than removing it. And cost control is not authorization and not an execution deadline — it bounds what a caller may ask for, not what they may see or how long a single field may take. If your graph is first-party only, the honest alternative is to skip scoring altogether and admit only documents you have measured; a cost model earns its keep precisely when you cannot enumerate the documents in advance.