FAQ

Short answers to the questions that come up most. Each links to the page with the full story.

Does costQL call my API when I quote a query?

No. Quoting is fully offline. The build makes real calls once, to learn your API, and saves what it learned as the pricing pack. After that, your app prices queries against that static file with no network calls. See Quickstart.

What is a price in? Is it dollars?

Work-time: how much real work a query causes on your server, in milliseconds (the pack calls this a cost-unit). It is not dollars. You map cost-units to whatever you charge in your own app. This keeps costQL honest about cost and leaves pricing to you.

Do I have to change my server?

Not to start. Your first pack (T1) times whole queries from the outside and needs no server changes at all. The instrumented tiers (T2, T3) ask your server to report per-resolver work; that’s the one change, covered in Instrumenting for T2/T3. Which tier fits is a fact about your API, not a ranking: see Tier fidelity.

Can it price a call to a paid API, like an LLM?

The work a paid call takes is timed automatically, like any other field. But costQL can’t know what an outside service charges you, so it doesn’t guess: it names the call (the host, and how many) and your app puts the price on it. Here is how: External calls.

What happens when my schema changes?

Rebuild the pack (minutes of measurement). Every quote carries a schema_hash, so a consumer comparing hashes notices drift. Any fees you authored survive the rebuild.

What is the difference between typical and safe max? (the two numbers on every quote)

Every quote gives you two numbers, because a query’s real cost depends on how many items its lists return, which you cannot know for sure until you run it.

• Typical (the typical_price field) is what the query usually costs. costQL assumes each list comes back at its average size. Use it to understand normal, everyday cost.
• Safe max (the price field) is the most it could cost. costQL assumes the largest sizes it has seen, and it is guaranteed never to fall below the real cost. Price on it whenever never undercharging matters.

They are equal when a query’s size is fixed (bounded lists, single objects) and differ only when a query could balloon in size. Rideshare rule: “usually $12, never more than $18.” See the output contract.

What about queries costQL can't predict well?

It says so. Hard-to-predict shapes (for example, cyclic queries) come back with confidence: "low" rather than a falsely precise number. The limitations page lists what costQL does not try to do.