Metering & idempotency

The unit meter is the product — this page is the exact contract your billing expectations should be built on.

What gets metered

Only successful (2xx) requests to /v1/{domain}/* data endpoints consume units. Core endpoints (/v1/usage, /v1/me, webhook management, /v1/meta/*) are always free and unmetered. Auth failures (401/403) and rate-limit rejections (429) never charge units.

Unit costs

Cost	Applies to
1 unit	Default — most `GET /v1/legal/*` reads (documents, effectivity, relations, changes, `search` with `mode=fts`)
2 units	`GET /v1/legal/search` with `mode=semantic` or `mode=hybrid` (Builder+)
100 units	`GET /v1/legal/export` (Pro)
0 units	Idempotent replays (see below)

Cost is declared per-route and returned on every metered success via the X-CrawlPipe-Units-Charged response header, alongside X-CrawlPipe-Units-Remaining for the current billing period.

Idempotency

Send an Idempotency-Key: <uuid> header on any request. Within a 24-hour window:

Same key + same request (identical params/body hash) → the cached response is replayed verbatim, meta.units_charged is 0, and meta.idempotent_replay: true is set. Safe to retry after a timeout without double-billing.
Same key + a different request → 409 idempotency_conflict. Reusing a key for a different call is a bug on the caller's side, not a retry.

This is the mechanism that makes agent-style retry loops safe: an agent that doesn't know whether its last call succeeded can always retry with the same Idempotency-Key and be charged at most once.

Quotas

Plans include a fixed monthly unit allowance (plan.included_units — see Pricing). There is no overage billing in v1: once the quota is exhausted, requests get 429 quota_exceeded until the period rolls over or you upgrade. Your org gets an email at 80% of quota, once per period.

Rate limits

Independent of the unit quota, each plan also has a requests-per-minute limit enforced in a fixed 1-minute window. Exceeding it returns 429 rate_limited with a Retry-After header — this does not consume units.