Skip to main content
Idempotency-Key is an optional Header for all five paid POST operations: Entity Search create_task, Contact Search, Deep Search, Enrich, and Extract.
When you omit it, Lev8 generates a key and returns the final value in the response’s Idempotency-Key Header. Keys you provide are trimmed and must contain at most 128 characters.
Omitting the Header is convenient for one-off requests. For production jobs that must survive timeouts or process restarts, generate and persist a stable key before sending the request.

​
Scope

Idempotency is scoped to the exact API credential and key. Two API keys owned by the same user do not share idempotency records, even though they share billing and user-level concurrency. The request body is normalized and hashed. Reusing a key with different input returns 409 idempotency_error and does not start another search.

​
Replay behavior

Neither successful replay calls the search service or bills the request again. An Entity Search request is replayable only during its fixed recovery window. Once that window expires and the reservation is refunded, replay returns 409 request_expired and the old task cannot be reopened by polling.
  1. Generate a UUID when your application creates a logical operation.
  2. Persist the key and canonical input before sending the request.
  3. Reuse both after a timeout, disconnect, or process restart.
  4. Store the returned Idempotency-Key, X-Request-Id, and leads_search_id with the operation.
  5. Generate a new key only for an intentional new search.
Xiaohongshu and WeChat Official Account searches usually take 1 to 2 minutes before results are ready. Keep polling the existing leads_search_id instead of creating a new task with a new idempotency key.
If you omit the key and lose the entire response, you also lose the server-generated value. Retrying can then start a second billable operation.

​
MCP behavior

The hosted MCP endpoint does not expose idempotency_key in any Tool schema. It generates a new internal key for each paid POST Tool and does not automatically retry paid operations. Calling entity_search_create, contact_search, deep_search, enrich, or extract again is a new billable operation.