Skip to main content
Entity Search and Contact Search use lev8 credits. Prices, enabled entity types, enabled contact types, and Contact Search billing mode are configured for each rollout; this documentation intentionally does not publish draft or test rates as production prices.

​
Check available credits

Call GET /v1/credit/balance with an active API key to read the credits currently available for a new request. The value combines all usable credit sources and excludes credits already reserved by in-progress requests. The balance response is deliberately account-level: it does not expose paid, monthly, subscription, or promotional bucket details, and it cannot be used to query another user. Responses include Cache-Control: no-store.

​
Request lifecycle

1

Reserve

Before calling the search service, lev8 reserves the maximum possible cost: requested limit multiplied by the configured unit price. If the balance cannot cover the reservation, the API returns 402 insufficient_credits.
2

Meter

lev8 counts entities from unique batch_index values. A repeated identical batch is not metered twice.
3

Settle

After a complete successful stream, lev8 charges for the metered entity count and returns the unused part of the reservation to its original credit buckets. A successful zero-result search settles at zero units.
4

Release or reconcile

A failure before any entities are returned releases the full reservation. A failure after partial results, a client disconnect, a protocol failure, or a settlement failure can retain the reservation and mark the request for reconciliation.

​
Important boundaries

  • Billing is recorded synchronously in lev8’s transactional ledger; it does not depend on asynchronous message delivery.
  • Promotional and standard credit buckets are restored to their original source when unused reserved credits are returned.
  • [DONE] confirms the SSE protocol ended, but settlement happens immediately after streaming and cannot be reported back on the completed stream.
  • Multiple API keys owned by the same user share the same billing subject and user-level concurrency allowance.
  • Contact Search reserves one lookup at its configured email or phone price. Depending on the rollout, a completed request is charged either per request or only when result.content contains a result.
  • Contact Search validates the upstream JSON and settles before returning a successful response. Upstream or protocol failures release the reservation; settlement uncertainty returns an error and requires reconciliation.
  • Contact Search pricing, enrichment surcharges, and final production Entity Search rates are provided separately for each rollout rather than published here.
If a stream returns partial results and then emits an error, retain X-Request-Id and leads_search_id. Do not automatically repeat the request with a new idempotency key.