Pricing
Per-row base prices
Each source publishes a price in cents per row — see GET /v1/sources:
{
"pricing": {"block_size": 100, "block_exponent": 0.5},
"sources": [
{"name": "a", "rows": 123123, "price_cents_per_row": 100},
{"name": "b", "rows": 45678, "price_cents_per_row": 10},
{"name": "c", "rows": 9012, "price_cents_per_row": 1}
]
}
Every unit bills at its cheapest source's price (see attribution).
The volume ladder
Units in your matched set are sorted most-expensive-first, and each unit's position in that list determines a multiplier:
| Block | Ladder positions | Rows in block | Per-row multiplier |
|---|---|---|---|
| 1 | 0–99 | 100 | 1.0 |
| 2 | 100–299 | 200 | 0.5 |
| 3 | 300–699 | 400 | 0.25 |
| 4 | 700–1499 | 800 | 0.125 |
| 5 | 1500–3099 | 1600 | 0.0625 |
| 6 | ≥ 3100 | ∞ | 0.05 |
Each block doubles in size and halves in price, until reaching the floor. A unit's cost is:
cost = source price (cents) × block multiplier
Because the expensive units sit at the top of the ladder, total cost grows roughly logarithmically with match size — about USD 1,340 for a million rows at a USD 1 base price. Bigger matches are dramatically cheaper per row.
Worked example
Sources a = 100¢, b = 10¢, c = 1¢. A query matches 2234 units, attributed a: 1000, b: 100, c: 1134. Sorted by price, all a units take positions 0–999, b takes 1000–1099, c takes the rest:
| Positions | Source | Units | Multiplier | Cost |
|---|---|---|---|---|
| 0–99 | a | 100 | 1.0 | $100.00 |
| 100–299 | a | 200 | 0.5 | $100.00 |
| 300–699 | a | 400 | 0.25 | $100.00 |
| 700–999 | a | 300 | 0.125 | $37.50 |
| 1000–1099 | b | 100 | 0.125 | $1.25 |
| 1100–1499 | c | 400 | 0.125 | $0.50 |
| 1500–2233 | c | 734 | 0.0625 | $0.45875 |
Exact total: 33971 cents, for 2234 units — about $0.15 per unit despite a $1.00 headline price.
Guarantees
- Exactness. All arithmetic is integer/fixed-point internally. Prices are exact; rounding happens once per charge. You will never see float drift.
- Chunking invariance. Rounding is applied to cumulative totals, so any partition of a lineage into chunks bills chunks summing to exactly the one-shot price. In the example above, one run split 2234 units as 1000/1000/234 and billed 15130 + 15002 + 3839 = 33971 cents.
- Zero-cost chunks are normal. Once you're deep in the cheap tail, a small chunk can legitimately cost 0 cents. This is correct, not a bug.
- Frozen prices. Your lineage's prices are locked at root creation; later price changes don't affect orders already in flight.
Previewing cost
POST /v1/count is free and returns est_total_cost_cents for the full match, plus est_cost_cents for the first max_rows units. The subset estimate is computed in expectation — the exact subset cost depends on which units the deterministic ordering selects and is only final at execution. Treat /v1/count as a close estimate, not a quote: the database can change between the count and the search.