Entity Search

Entity Search runs as an asynchronous task:

POST /v1/entity-search/create_task creates a search task and returns leads_search_id.
GET /v1/entity-search/status returns task progress and ready_count.
GET /v1/entity-search/fetch returns results from a position pts with a maximum batch size num.

The task may produce results while it is still running. A client is done reading when the task status is done or error and the client has fetched every result up to ready_count.

Headers

Header	Required	Description
`Content-Type: application/json`	For `create_task`	Other media types return `422`.
`Accept: application/json`	Recommended	Declares that the client expects a JSON response.
`Authorization`	Yes	`Bearer lev8_live_...` — your active Lev8 API key.
`Idempotency-Key`	No	Optional stable value up to 128 characters. When omitted, Lev8 generates one and returns it in the same response Header.

Create task

POST /v1/entity-search/create_task

Request body

Field	Type	Required	Default	Description
`entity_type`	string enum	Yes	-	Entity type to search. See supported entity types. Use `wechat` for WeChat Official Account search. `xiaohongshu` and `wechat` require `enable_web_search: true` and usually take 1 to 2 minutes to produce results.
`objective`	string	Yes	-	Natural-language search target, 1 to 4,000 UTF-8 bytes after trimming.
`limit`	integer	No	`20`	Maximum number of deduplicated entities to produce, from `1` to `500`; the service can return fewer.
`enable_web_search`	boolean	Conditional	`false`	Keeps database search and additionally enables open web search mode. Required and must be `true` when `entity_type` is `xiaohongshu` or `wechat`.
`enrich_fields`	string[]	No	omitted	Extra fields to return under `entities[].enrich_fields`, up to 20 items. Not suitable for finding email addresses or phone numbers; use Contact Search for contact details.
`dedup_lev8_leads`	string[]	No	omitted	Previous `leads_search_id` values whose results should be excluded, up to 100 items.
`dedup_custom_leads`	string[]	No	omitted	Existing lead names to exclude from this task, up to 1,000 items.

The complete JSON body must be at most 1 MiB. Unknown fields, malformed JSON, and multiple JSON objects are rejected.

Enable web search

enable_web_search: true keeps the default database search and also turns on open web search mode. Use it for creator searches on X/Twitter, YouTube, TikTok, Instagram, Xiaohongshu, or WeChat Official Accounts, Shopify store discovery, or highly time-sensitive searches such as entities from the last 30 days. Turning it on usually increases latency and cost, so keep it false unless broader or fresher discovery is needed.

Requests with entity_type: "xiaohongshu" or entity_type: "wechat" must include enable_web_search: true. Omitting enable_web_search or setting it to false returns 422 invalid_request_error. These searches usually take 1 to 2 minutes before results are ready.

Deduplicate results

Use deduplication when you already have leads that should not appear again. The task produces up to limit deduplicated leads after these exclusions.

{
  "dedup_lev8_leads": ["leads_search_01JABCDEF123456789"],
  "dedup_custom_leads": ["Figure AI", "Perplexity AI"]
}

dedup_lev8_leads excludes leads from earlier Lev8 searches by leads_search_id.
dedup_custom_leads excludes your existing leads by name.

Enrich fields

By default, entities include name, links, description, and score. Use enrich_fields to request additional descriptive fields, such as funding stage or headcount. Each returned enrichment generally includes content and reference. Do not use enrich_fields to find email addresses or phone numbers; use Contact Search for contact details.

{
  "enrich_fields": ["funding stage", "headcount"]
}

Supported entity types

`entity_type`	Description
`company`	Company entities.
`person`	Person entities.
`twitter_creator`	X/Twitter creators.
`youtube_creator`	YouTube creators.
`tiktok_creator`	TikTok creators.
`instagram_creator`	Instagram creators.
`shopify_store`	Shopify stores.
`xiaohongshu`	Xiaohongshu accounts. Requires `enable_web_search: true`; results usually take 1 to 2 minutes.
`wechat`	WeChat Official Accounts. Requires `enable_web_search: true`; results usually take 1 to 2 minutes.

Example

curl "https://app.lev8.com/v1/entity-search/create_task" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $LEV8_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "entity_type": "company",
    "objective": "AI startups that raised Series A in 2024",
    "limit": 20,
    "enrich_fields": ["funding stage", "headcount"]
  }'

Response

{
  "object": "entity_search_task",
  "leads_search_id": "leads_search_01JABCDEF123456789",
  "entity_type": "company",
  "objective": "AI startups that raised Series A in 2024",
  "limit": 20,
  "status": "created",
  "created_at": "2026-08-04T00:00:00Z"
}

Field	Type	Description
`object`	string	Always `entity_search_task`.
`leads_search_id`	string	Search task ID for later `status` and `fetch` calls. It can also be used in later `dedup_lev8_leads` requests.
`entity_type`	string	Entity type used by the task.
`objective`	string	Search objective used by the task.
`limit`	integer	Maximum number of entities this task should produce.
`status`	string	Usually `created`; an idempotent replay can return the task’s current state.
`created_at`	string	UTC RFC 3339 timestamp for task creation.

The response includes Idempotency-Key, X-Request-Id, and Cache-Control: no-store. Store all three values when the task must be recoverable after a lost connection.

Check status

GET /v1/entity-search/status

Query parameters

Parameter	Type	Required	Description
`leads_search_id`	string	Yes	The task ID returned by `create_task`.

Example

curl "https://app.lev8.com/v1/entity-search/status?leads_search_id=leads_search_01JABCDEF123456789" \
  --header "Authorization: Bearer $LEV8_API_KEY"

Response

{
  "object": "entity_search_status",
  "leads_search_id": "leads_search_01JABCDEF123456789",
  "status": {
    "status": "running",
    "verified_count": 12,
    "ready_count": 10
  }
}

Field	Type	Description
`object`	string	Always `entity_search_status`.
`leads_search_id`	string	Search task ID.
`status.status`	string	One of `created`, `running`, `done`, or `error`.
`status.verified_count`	integer	Number of entities checked so far, including accepted and rejected candidates.
`status.ready_count`	integer	Number of result entities currently available through `fetch`.
`status.stop_reason`	string	Terminal reason when available; omitted otherwise.
`status.error`	string	The fixed value `internal error` for a failed task; omitted otherwise.

verified_count includes accepted and rejected candidates, so it is always greater than or equal to ready_count. Known stop_reason values include limit, source_finished, no_data_timeout, and rejected_streak.

Xiaohongshu and WeChat Official Account tasks commonly remain running for 1 to 2 minutes before ready_count increases.

Fetch results

GET /v1/entity-search/fetch

Query parameters

Parameter	Type	Required	Default	Description
`leads_search_id`	string	Yes	The task ID returned by `create_task`.
`pts`	integer	No	`0`	Result start position. The first result is position `0`.
`num`	integer	No	`5`	Maximum number of results to return in this call. The service can return fewer.

The response does not include a next cursor. After each fetch, compute the next pts as the current pts + count.

Example

curl "https://app.lev8.com/v1/entity-search/fetch?leads_search_id=leads_search_01JABCDEF123456789&pts=0&num=5" \
  --header "Authorization: Bearer $LEV8_API_KEY"

If the first fetch returned count: 1, the next position is 0 + 1 = 1:

curl "https://app.lev8.com/v1/entity-search/fetch?leads_search_id=leads_search_01JABCDEF123456789&pts=1&num=5" \
  --header "Authorization: Bearer $LEV8_API_KEY"

Response

{
  "object": "entity_search_items",
  "leads_search_id": "leads_search_01JABCDEF123456789",
  "status": "running",
  "pts": 0,
  "num": 5,
  "count": 1,
  "ready_count": 1,
  "limit": 20,
  "entities": [
    {
      "name": "Figure AI",
      "links": {
        "website": "https://www.figure.ai",
        "linkedin_url": "https://www.linkedin.com/company/figure-ai"
      },
      "description": "AI robotics company building general purpose humanoid robots.",
      "score": {
        "score": "high",
        "reason": "..."
      },
      "enrich_fields": {
        "funding stage": {
          "content": "Series B",
          "reference": "..."
        }
      }
    }
  ]
}

Field	Type	Description
`object`	string	Always `entity_search_items`.
`leads_search_id`	string	Search task ID.
`status`	string	Current task status: `created`, `running`, `done`, or `error`.
`pts`	integer	Result start position used by this response.
`num`	integer	Requested maximum result count.
`count`	integer	Actual number of entities returned. Use `pts + count` for the next fetch.
`ready_count`	integer	Total number of result entities currently available to fetch.
`limit`	integer	Maximum number of entities this task should produce.
`entities`	array	Result entities for this position range.

Entity fields

Field	Type	Description
`entities[].name`	string	Unified entity name.
`entities[].links`	object	Link fields with non-empty values only.
`entities[].description`	string or null	Entity description when available.
`entities[].score`	object	Relevance score and explanation.
`entities[].enrich_fields`	object	Extra fields requested through `enrich_fields`.

Common links fields by entity type:

`entity_type`	`links` fields
`company`	`website`, `linkedin_url`, `twitter_url`, `instagram_url`, `tiktok_url`, `youtube_url`, `github_url`
`person`	`linkedin_url`
`twitter_creator`	`twitter_url`
`youtube_creator`	`youtube_url`
`tiktok_creator`	`tiktok_url`
`instagram_creator`	`instagram_url`
`shopify_store`	`main_page`
`xiaohongshu`	Platform URL fields when available.
`wechat`	Official Account URL fields when available.

Complete workflow examples

See Task results for complete Node.js and Python examples that create a task, poll status, and fetch every result.

Errors

Entity Search uses the standard error envelope.

Status	Meaning
`401`	API key is missing or invalid.
`402`	The account cannot reserve the maximum task cost.
`403`	API key is revoked, expired, or lacks Entity Search access.
`404`	`leads_search_id` does not exist or belongs to another API key.
`409`	The idempotency key conflicts with another body, task creation is unresolved, or the replay window expired.
`422`	Validation failed, such as unsupported `entity_type`, omitted or false `enable_web_search` for `xiaohongshu` or `wechat`, invalid `limit`, invalid `pts` or `num`, or invalid `enrich_fields`.
`429`	The user-level or global active-task limit was reached.
`500`	Server error.
`503`	Entity Search or pricing for this entity type is not enabled.

Authentication, billing, concurrency, and service availability errors are documented in Errors.

Getting started

API reference

MCP

API behavior

Headers

Create task

Request body

Enable web search

Deduplicate results

Enrich fields

Supported entity types

Example

Response

Check status

Query parameters

Example

Response

Fetch results

Query parameters

Example

Response

Entity fields

Complete workflow examples

Errors

​Headers

​Create task

​Request body

​Enable web search

​Deduplicate results

​Enrich fields

​Supported entity types

​Example

​Response

​Check status

​Query parameters

​Example

​Response

​Fetch results

​Query parameters

​Example

​Response

​Entity fields

​Complete workflow examples

​Errors

Headers

Create task

Request body

Enable web search

Deduplicate results

Enrich fields

Supported entity types

Example

Response

Check status

Query parameters

Example

Response

Fetch results

Query parameters

Example

Response

Entity fields

Complete workflow examples

Errors