Usage and billing

What is billed

MasterDB bills what it observed itself serve:

Billed: one query	Never billed
a search that returns at least one row	a search that returns no rows
a fetch that returns a record	a fetch answered 404
	a refusal (any 4xx: a bad signature, an invalid query, a rate limit)
	MasterDB’s own failures (any 5xx)

Each signed request is billed once — counted by its (keyid, nonce) — whichever and however many regions answered it. Zero-result searches are free and carry no restriction beyond the ordinary rate limit: explore freely.

Queries are priced from your company’s rate card in marginal tiers over the billing period: each tier’s rate applies only to the queries inside it, and the first tier is a free allowance. Your rate card is shown in the AI Portal. Receipts are the record: the bill is the receipts, counted.

Usage

GET /v1/usage answers your group’s usage: searches, fetches and billable queries by day, key, legal entity and collection, and where the period stands in your tiers. It never contains any figure about blocks — no count, no band.

TypeScript

samples/typescript/usage.ts

// Usage: your queries by day, key, legal entity and collection, and where you are in your tiers.
import assert from 'node:assert/strict';
import { createPrivateKey } from 'node:crypto';
import { readFileSync } from 'node:fs';
import { SANDBOX, createEd25519Signer, createRetrievalClient } from '@masterdb/client';

const signer = createEd25519Signer(createPrivateKey(readFileSync(process.env.MASTERDB_KEY_FILE as string)));
const client = createRetrievalClient({ baseUrl: process.env.MASTERDB_API_URL ?? SANDBOX.retrieval, signer });

const usage = await client.GET('/v1/usage');
if (usage.error) throw new Error(usage.error.code);
console.log('as at', usage.data.as_at);
for (const d of usage.data.days) console.log(d.date, d.collection, 'searches', d.searches, 'fetches', d.fetches, 'billable', d.billable);
for (const t of usage.data.tiers ?? []) console.log('tier', t.tier, t.from_queries, '-', t.to_queries, 'consumed', t.consumed);
// There is no figure about blocks anywhere in usage: not a count, not a band.
assert.ok(!JSON.stringify(usage.data).includes('block'));

Python

samples/python/usage.py

"""Usage: your queries by day, key, legal entity and collection, and where you are in your tiers."""

import os

import httpx
from masterdb_signing import SANDBOX_API, MasterDBAuth, load_key

client = httpx.Client(
    base_url=os.environ.get("MASTERDB_API_URL", SANDBOX_API),
    auth=MasterDBAuth(load_key(os.environ["MASTERDB_KEY_FILE"])),
)

usage = client.get("/v1/usage")
usage.raise_for_status()
data = usage.json()
print("as at", data["as_at"])
for d in data["days"]:
    print(d["date"], d["collection"], "searches", d["searches"], "fetches", d["fetches"], "billable", d["billable"])
for t in data["tiers"]:
    print("tier", t["tier"], t["from_queries"], "-", t["to_queries"], "consumed", t["consumed"])
# There is no figure about blocks anywhere in usage: not a count, not a band.
assert "block" not in usage.text

Paying

A company pays by prepayment (card or bank transfer), or, once approved, by monthly invoice. Advertising revenue MasterDB has collected on your behalf is netted against what you owe, monthly, and each month closes with a statement.

The prepaid stop. A prepay company whose allowance is spent is answered 402 with the code allowance_exhausted. A small overrun at the moment the allowance runs out is possible, and is charged. If your allowance cannot be confirmed, requests are answered 503 unavailable with Retry-After until it can: the stop fails closed, and those 503s are not billed.

In the sandbox

Billing is computed and shown on the usage screens, and never invoiced or paid. Rate limits are the same as in production (Rate limits).