Priced Before It Runs

Pricing a Query Nobody Has Seen Yet

GraphQL's flexibility is exactly what makes it hard to bill. A REST endpoint does one thing at one cost; a GraphQL endpoint answers whatever shape of question the caller composes, and two queries that look similar can differ in cost by orders of magnitude. Flat per-request pricing overcharges the small queries and undercharges the expensive ones, while static complexity scoring assigns points to fields nobody ever measured.

Machine-driven traffic raises the stakes. When the caller is an agent composing queries on its own, there is no human in the loop to notice a bad number. A wrong price becomes a live billing problem the moment it ships. And metering after execution doesn't solve it: by the time the meter reads, the server has already done the work.

What was missing was a way to quote any query in advance, accurately and offline, that stayed honest about its own uncertainty when the tool wasn't sure.

Calibrate Once, Quote Anywhere

costQL turns a live endpoint into a pricing oracle in three steps. A short adapter file (about 90 lines) tells it where the API lives and gives it real IDs to query with. Then `costql build` sends calibration queries at the API, times the answers, and learns per-resolver cost curves from measured behavior rather than assigned scores. Everything it learns is saved as one JSON file: the pricing pack.

The pack is the product. Load it in Python or JavaScript and price queries right where your code runs, with zero network calls, no server, and both languages returning the exact same answer. Every quote is expressed in work-time (shown as work-ms in the tool): how much real work a query causes on the server. Each quote carries two numbers, a typical price for what the query usually costs and a safe max sized so that billing on it never undercharges, plus a confidence rating that flags low-confidence quotes instead of failing silently.

Because APIs differ in what they can report, costQL meets each one at its own fidelity. Tier 1 puts a single stopwatch on the whole query from outside, with no server changes. Tier 2 reads per-resolver timings so parallel work stops hiding inside one clock. Tier 3 also counts batched and reused reads once instead of once per row. No tier is better than another. The right one is a fact about the API. Fields that call paid outside services, like an LLM or a licensed data feed, are named in the quote so the application can put its own price on them rather than letting costQL guess.

Designing What the Tool Refuses to Claim

I designed and shipped the system end to end: the calibration-over-scoring approach, the pricing pack as a single portable artifact, the three-tier fidelity model, the adapter interface, and the cross-language contract that Python and JavaScript must quote identically. The ML and numerical implementation was AI-assisted; the work I claim is the design and systems judgment: deciding what had to be measured instead of guessed, what the defaults had to protect, and what the tool must refuse to claim when it isn't sure.

The honesty defaults were the hardest design decisions. Billing on the safe max by default means the tool never quietly undercharges. Surfacing confidence means a shaky quote arrives flagged rather than dressed up as certainty. Naming external calls instead of pricing them means costQL doesn't invent numbers for services it can't see. I also built the proof surface: a browser playground with three real demo APIs calibrated into live packs, priced offline as you type with no signup, plus the documentation and finished adapter examples that take a new user from endpoint to quote in about a minute.

Live, Offline, and Hard to Break

costQL is live: `pip install costql` and `npm install costql` both work today, with CI running across Python 3.10 through 3.13 and the two runtimes held to identical answers. To validate the approach I calibrated three unrelated APIs, spanning different domains, schemas, and work profiles, into packs that price real queries in the browser at costql.com.

The three APIs were chosen to be genuinely different kinds of cost. TMDB is a network passthrough, where the price is dominated by outbound HTTP round-trips. Rick & Morty is a public API costQL doesn't own and can't change. It's the real-world test of pricing a stranger's endpoint. Northwind is a SQL-backed store database, where queries batch and reuse reads and the cost lives in the database, not the network. One unchanged engine priced all three.

The result is infrastructure for a problem that is arriving fast: as agent-driven traffic grows, API operators need prices that exist before execution and hold up with no human watching. A pricing pack is small enough to ship inside an application, honest enough to bill on, and self-contained enough to need zero servers. It is the working proof of the bar the rest of my work is built to: measurable, honest, and hard to break.