> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lev8.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits and billing

> Understand reservation, settlement, release, and reconciliation behavior.

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`](/api-reference/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

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Meter">
    lev8 counts entities from unique `batch_index` values. A repeated identical batch is not metered twice.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<Note>
  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.
</Note>