# costQL

> Price GraphQL queries before you run them: calibrate a live API into a static
> pricing pack, then quote any query offline: in Python or JavaScript. Cost-units
> only, never dollars. No hosted service; the pack is a plain local file.

Install: `pip install costql` (build + quote) · `npm install costql` (quote only)

## Docs

- [Writing an adapter](https://costql.com/docs/adapters/): An adapter is the one file you write to onboard an API, proven at ~90–150 lines across three unrelated APIs, with zero engine changes. It tells costQL what intr
- [Agent-assisted onboarding](https://costql.com/docs/agents/): The fastest way to onboard an API is to hand it to a coding agent (Claude Code, Cursor, or any tool that can read a repo and run a CLI) instead of writing the a
- [How pricing flows: build → pack → quote](https://costql.com/docs/architecture/): 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
- [The output contract (v1.0)](https://costql.com/docs/contract/): Every price costQL produces (at any tier, on any query, predicted or measured) follows one frozen, stable shape. This is the contract an application budgets aga
- [The three demo APIs and their packs](https://costql.com/docs/demo-apis/): costQL was proven against three real, unrelated GraphQL APIs: a network passthrough we instrumented (TMDB), a public API we don't own and can't change (Rick & M
- [How costQL measures its own accuracy](https://costql.com/docs/evaluation/): Any accuracy number needs three pieces: a **model** whose prediction is on trial, a **baseline** (ground truth) to compare against, and a **dataset** the compar
- [Instrumenting your server for T2/T3](https://costql.com/docs/instrumentation/): T1 needs nothing from your server: costQL times whole requests from the outside. The richer tiers need the server to *tell* costQL what work a request actually 
- [The JS package](https://costql.com/docs/js/): `npm install costql` gives you the **quote side** of costQL in JavaScript/TypeScript: load the same pack file the Python engine writes and price queries offline
- [Honest limitations](https://costql.com/docs/limitations/): costQL's core guarantee (a billable `price` on every query, with a ceiling that never under-prices) holds everywhere we have measured it. But some queries are g
- [Quickstart](https://costql.com/docs/quickstart/): costQL turns a live GraphQL API into a **pricing pack** (one self-contained JSON file) and then quotes any query against that pack fully offline. Build once in 
- [Case study: a batch-heavy database backend](https://costql.com/docs/results/northwind/): On the [TMDB demo](tmdb.md), the middle fidelity (T2) priced queries just as well as the top fidelity (T3), but TMDB shares entities only lightly. To find out w
- [Case study: pricing a stranger's API (Rick & Morty, T1)](https://costql.com/docs/results/rickmorty/): Does costQL work on an API it has never seen, that we don't own and can't change? This experiment pointed it at the public **Rick & Morty API** (`rickandmortyap
- [Case study: three-tier accuracy on the TMDB demo](https://costql.com/docs/results/tmdb/): Measured against the **real** TMDB demo API (live data, work-ms currency, zero Anthropic calls), this experiment answers a standing question head-on: **do you n
- [One currency, three fidelities](https://costql.com/docs/tiers/): costQL prices everything in one currency, **work-ms** (the summed duration of the real work a query causes), and offers three *tiers* that are fidelities of one

## Source

- [GitHub](https://github.com/shapemachine/costql): engine, adapters, demos, packs, conformance oracle