Skip to main content
Entity Search, Contact Search, Deep Search, Enrich, and Extract use Lev8 credits. The rates below apply to the currently enabled public rollout.

​
Check available credits

Call GET /v1/credit/balance with an active API key. available_credits combines all usable sources and excludes credits already reserved by active requests. The response does not expose paid, monthly, subscription, or promotional bucket details, and it cannot query another user. Responses include Cache-Control: no-store.

​
Credit charges

The final charge depends on the task’s terminal status:
  • done: startup credits + ready_count × per-result credits
  • error: ready_count × per-result credits; the startup credits are refunded
Set enable_web_search: true to use the open web startup rate instead of the standard startup rate. xiaohongshu and wechat always require enable_web_search: true; requests that omit it or set it to false fail validation before credits are reserved. These tasks usually take 1 to 2 minutes before results are ready.

​
Deep Search and Enrich

​
Extract

For social and GitHub extraction, Lev8 reserves the maximum cost from limit before calling the upstream service, then settles from the number of successfully returned items. web2list reserves its fixed 80-credit price.

​
Example

Finding 10 companies with standard Entity Search costs 5 + (10 × 2) = 25 credits. Finding one email address for each company costs another 10 × 10 = 100 credits, for a total of 125 credits. If fewer than 10 companies are returned, Entity Search charges only for its final ready_count.

​
Entity Search lifecycle

1

Reserve

Before creating the upstream task, Lev8 freezes the configured startup fee plus limit × result unit price. enable_web_search can select a different startup fee. Insufficient balance returns 402 insufficient_credits.
2

Run

The task occupies user-level and global active-task capacity until it reaches a terminal state. Lev8 continues monitoring it even when the client is disconnected.
3

Settle

A done task charges the startup fee plus ready_count × result unit price. An error task refunds the startup fee and charges only its ready_count results. All unused frozen credits return to their original sources.
4

Recover

A task with an unknown creation result or no terminal state keeps its reservation temporarily. After the configured recovery period, Lev8 refunds it and releases the active-task slot.
Status requests and background processing share the same idempotent terminal settlement behavior. Repeated finalization cannot charge the task twice. The recovery deadline is fixed when the reservation is created. Status and Fetch calls do not extend it. After the deadline and any in-flight response delivery complete, Lev8 refunds an unresolved reservation, releases the active-task slot, and stops exposing the old task results.
ready_count is the billing result count. verified_count also includes candidates that were checked and rejected, so it is not used as the charged quantity.

​
Contact Search

Contact Search freezes the configured email or phone price before calling the search service. It charges only when result.content is non-empty after trimming. A not-found response costs zero credits and releases the full reservation. The successful response and settlement are saved together. Replaying the same API key, Idempotency-Key, and body returns the saved JSON without another upstream request or charge.

​
Synchronous workflow settlement

Deep Search, Enrich, and Extract also save a successful response and settle credits together. A replay with the same API key, Idempotency-Key, and request body returns that saved response without another upstream call or charge. These APIs use request-duration concurrency leases rather than Entity Search task slots. A timeout or lost response does not prove that the operation failed, so preserve the original idempotency key when retrying.

​
Important boundaries

  • Billing is recorded transactionally and does not depend on asynchronous message delivery.
  • Multiple API keys owned by the same user share the same balance and user-level concurrency limit.
  • Entity Search concurrency counts active asynchronous tasks, not HTTP connections. Status and Fetch do not consume new slots.
  • Contact Search, Deep Search, Enrich, and Extract use synchronous request concurrency limits.
  • An Entity task with terminal error can still contain charged, readable results.
  • Upstream failures and internal details are redacted from public responses.
  • Pricing is supplied separately for each enabled rollout.