Quickstart

Before you begin

You need:

An API base URL assigned by lev8.
An active API key with Entity Search access.
Enough credits to reserve the maximum cost of the request.
A server-side HTTP client that can consume Server-Sent Events (SSE).

Set server-side environment variables

Keep API keys out of browser code, mobile apps, source control, and logs.

export LEV8_API_BASE_URL="https://your-assigned-api-host"
export LEV8_API_KEY="lev8_live_..."

Check available credits

Confirm that the API key’s billing account has credits available for a new request.

curl "$LEV8_API_BASE_URL/v1/credit/balance" \
  --header "x-api-key: $LEV8_API_KEY"

The returned available_credits already excludes credits reserved by requests that are still in progress.

Send a streaming search request

Use --no-buffer so curl prints each SSE event as it arrives. Supply a unique Idempotency-Key for the logical request.

curl --no-buffer "$LEV8_API_BASE_URL/v1/entity-search" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Accept: text/event-stream" \
  --header "x-api-key: $LEV8_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "entity_type": "person",
    "objective": "VPs of Sales at Bay Area voice AI startups that launched in the last year",
    "limit": 10,
    "enrich_fields": ["current_company", "location"]
  }'

Process events until [DONE]

A successful stream contains zero or more entity_search_batch objects, one entity_search_done object, and a final [DONE] sentinel.

data: {"object":"entity_search_batch","batch_index":1,"count":2,"cum_count":2,"entities":[...]}

data: {"object":"entity_search_done","cum_count":2,"stop_reason":"source_finished","finish":true}

data: [DONE]

Save the X-Request-Id response header and the leads_search_id from stream events. They identify different layers of the request and are both useful when diagnosing a search.

Next steps

Check your balance

Read the current available-credit response and caching behavior.

Request fields

Choose an entity type, limit, enrichments, and deduplication inputs.

Find contact details

Request an email address or phone number as a JSON response.

Build a resilient consumer

Parse complete SSE frames, deduplicate batches, and handle stream errors.

Getting started

API reference

API behavior

Before you begin

Next steps

Check your balance

Request fields

Find contact details

Build a resilient consumer

​Before you begin

​Next steps

Check your balance

Request fields

Find contact details

Build a resilient consumer

Before you begin

Next steps