Skip to content
costQL

How pricing flows: build → pack → quote

This is costQL end to end: a new API arrives, the engine calibrates it into a static pricing pack, and from then on any app quotes queries against that pack locally: no server, no network, no re-measurement. The cost unit is always work-ms (summed real work; see One currency, three fidelities); the tiers differ only in how sharply the API lets costQL see and factor that work.

Nature of each step: the engine is 100% deterministic code (no LLM in the pricing path). The only non-engine touches are (a) a human-authored adapter + fee at onboarding, and (b) an external LLM that lives inside the API being priced, measured as a cost, never a costQL step.

flowchart TD
  subgraph LEGEND["LEGEND - nature of each step (the engine has NO agentic / LLM step)"]
    direction LR
    L1["DETERMINISTIC engine step<br/>plain code: schema walk, HTTP calls,<br/>a numeric regression, static analysis<br/>reproducible + auditable"]
    L2["HUMAN-AUTHORED once, at onboarding<br/>the API adapter (real inputs) +<br/>the seller's per-call fee"]
    L3["EXTERNAL LLM = a measured COST, not a step<br/>only if the API being priced calls one<br/>(e.g. an aiSummary resolver -> Haiku);<br/>costQL measures it, never invokes it itself"]
  end


  Start(["A new API arrives to be priced"]) --> S1


  %% ---------------- BUILD PHASE: learn the cost model ----------------
  S1["1 - Introspect the API live<br/>build its cost graph (types + resolvers)<br/>no schema file is kept in costQL's core"]
  S1 --> S2["2 - Mine real inputs  (API adapter, authored once)<br/>real ids / args so the sample queries actually run"]
  S2 --> S3["3 - Generate the coverage panel<br/>a targeted set of REAL queries:<br/>isolating + varied combinations + several sizes<br/>each run repeatedly under low contention"]
  S3 --> S4{"4 - What can this API expose?<br/>= the highest tier it affords"}


  S4 -->|"black box only"| T1
  S4 -->|"per-resolver timings"| T2
  S4 -->|"timings + sharing trace"| T3


  subgraph UNIT["HOW THE COST UNIT IS FACTORED  -  the unit is ALWAYS work-ms = summed real work (never elapsed wall-clock time)"]
    direction TB
    T1["T1 - CHEAP  (black box)<br/>----------<br/>Sees ONLY the whole-query wall-clock time<br/>(a low-fidelity stand-in for work-ms)<br/>Each resolver's cost is BACKED OUT by<br/>regression across many different queries<br/>BLUR: work done in parallel or batched<br/>hides inside elapsed time  ->  under-counts"]
    T2["T2 - MIDDLE<br/>----------<br/>Sees EACH resolver's own work-ms and<br/>sums the real durations<br/>(the count of calls x each call's weight)<br/>SHARING INFERRED: a call reused by<br/>several fields is guessed, not observed<br/>->  shared work can be double-counted"]
    T3["T3 - EXPENSIVE<br/>----------<br/>Sees each resolver's work-ms PLUS the<br/>sharing trace (which calls coalesced / deduped)<br/>Shared calls counted ONCE, and each shared loader<br/>priced by a LEARNED batch-size curve work-ms = f(distinct keys)<br/>(a 300-key batch costs more than a 3-key one;<br/>DB loader rises, network loader stays flat)<br/>external / paid hosts are named<br/>->  exact factoring, nothing hidden"]
  end


  T1 --> S5
  T2 --> S5
  T3 --> S5


  S5["5 - Fit the cost model<br/>solve:  op_cost  =  sum over resolvers of<br/>( invocations  x  unit_cost )<br/>result: one unit_cost per resolver"]
  S5 --> S6["6 - Observe result sizes<br/>keep BOTH the typical (average) size<br/>and the worst-case size per resolver"]
  S6 --> S7["7 - Adjustments file (unmeasurable fees)<br/>engine AUTO-FLAGS external / paid resolvers,<br/>then a HUMAN (seller) writes the per-call fee<br/>in cost-units  (only T3 can name the resolver)"]
  S7 --> S8["8 - Grade accuracy on a HELD-OUT set<br/>predict prices, then run those queries for real,<br/>compare predicted vs measured<br/>= costQL rating its own accuracy"]


  %% ---------------- HANDOFF: the static pricing pack ----------------
  S8 --> PACK[["PRICING PACK - the build-to-use handoff<br/>ONE static, self-contained file:  schema + cost model + authored fees<br/>no server · no sidecar · no extra API call · no re-measure<br/>vendor it into the app, or even embed it in the API's own docs"]]


  %% ---------------- USE PHASE: price a query (app side, local) ----------------
  subgraph APPSIDE["APP SIDE - a quote is pure LOCAL computation from the pack (no service)"]
    direction TB
    Q(["Price a query  (a QUOTE - the query is NOT run)"])
    Q --> P1
    P1["Predict it from the pack ALONE - EVERY query, seen or unseen<br/>(the pack stores no query prices; there is no lookup)<br/>price = sum of ( unit_cost + authored_fee )  x  invocations<br/><br/>invocations = fanout counts multiplied down the query tree<br/>size basis:  typical size (fair quote)  OR  worst-case (safe ceiling)<br/>T3 prices each SHARED loader by its learned batch-size curve<br/>->  shared work counted once, a big batch costing more than a small one"]
    P1 --> P2{"is the query's size RUNTIME-UNKNOWABLE?<br/>(a) cyclic recursion re-enters a type via a list edge, OR<br/>(b) >=2 un-paginated list edges compound on one path"}
    P2 -->|"no  -  size is bounded / declared"| P3["HIGH confidence<br/>quote it"]
    P2 -->|"yes  -  size is data-dependent"| P4["LOW confidence<br/>structural quote + FLAG + caveat<br/>(ceiling stays SAFE; for an exact number, run it once  ->)"]
    P3 --> Out(["Priced query + confidence tag<br/>(the seller's app turns cost-units into money)"])
  end


  PACK --> Q
  P4 -->|"run it once (opt-in)"| P9
  P9["Exact cost from a RUN's work-ms receipt (the sharing trace)<br/>- OUTSIDE the local-only zone: this path actually RUNS the query.<br/>Reached ONLY when a caller opts in for an exact number on a<br/>low-confidence quote - never a cached panel price."]
  P9 --> Out


  %% ---------------- styling ----------------
  %% tiers (measurement fidelity)
  classDef cheap fill:#7c3f2e,stroke:#e8a87c,color:#fff;
  classDef mid   fill:#3a5a78,stroke:#8fb8d8,color:#fff;
  classDef exp   fill:#2e5e46,stroke:#86c9a0,color:#fff;
  class T1 cheap;
  class T2 mid;
  class T3 exp;


  %% nature of each step
  classDef engine fill:#eef2ff,stroke:#7f8fd0,color:#111;
  classDef human  fill:#fff3d1,stroke:#d9a300,color:#111;
  classDef extcost fill:#f3e0f0,stroke:#b567a4,color:#111;
  classDef pack fill:#dff3f7,stroke:#1b7f95,color:#111,stroke-width:3px;
  class S1,S3,S4,S5,S6,S8,P1,P2,P3,P4,P9 engine;
  class S2,S7 human;
  class PACK pack;
  class L1 engine;
  class L2 human;
  class L3 extcost;

The same flow, as commands

Section titled “The same flow, as commands”
  • Build (seller side, once per schema: steps 1–8 above): costql build --adapter examples/adapters/rickmorty.py:rickmorty_config --out pack.json
  • Quote (app side, local, the query is not run): costql quote --pack pack.json '<query>', or in Python, from costql import PricingPack; PricingPack.load("pack.json").quote(query). Quote-side is also available in JavaScript via the costql npm package.
  • Validate (any result against the frozen contract): costql validate --pack pack.json

Every quote and receipt follows the frozen output contract; the held-out grading in step 8 is specified in the evaluation methodology.