Create task

curl --request POST \
  --url https://app.lev8.com/v1/entity-search/create_task \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entity_type": "company",
  "objective": "AI startups that raised Series A in 2024",
  "limit": 20,
  "enable_web_search": false,
  "enrich_fields": [
    "funding stage",
    "headcount"
  ],
  "dedup_lev8_leads": [],
  "dedup_custom_leads": []
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entity_type: 'company',
    objective: 'AI startups that raised Series A in 2024',
    limit: 20,
    enable_web_search: false,
    enrich_fields: ['funding stage', 'headcount'],
    dedup_lev8_leads: [],
    dedup_custom_leads: []
  })
};

fetch('https://app.lev8.com/v1/entity-search/create_task', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.lev8.com/v1/entity-search/create_task"

payload = {
    "entity_type": "company",
    "objective": "AI startups that raised Series A in 2024",
    "limit": 20,
    "enable_web_search": False,
    "enrich_fields": ["funding stage", "headcount"],
    "dedup_lev8_leads": [],
    "dedup_custom_leads": []
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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"
}

POST

entity-search

create_task

Create task

curl --request POST \
  --url https://app.lev8.com/v1/entity-search/create_task \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entity_type": "company",
  "objective": "AI startups that raised Series A in 2024",
  "limit": 20,
  "enable_web_search": false,
  "enrich_fields": [
    "funding stage",
    "headcount"
  ],
  "dedup_lev8_leads": [],
  "dedup_custom_leads": []
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entity_type: 'company',
    objective: 'AI startups that raised Series A in 2024',
    limit: 20,
    enable_web_search: false,
    enrich_fields: ['funding stage', 'headcount'],
    dedup_lev8_leads: [],
    dedup_custom_leads: []
  })
};

fetch('https://app.lev8.com/v1/entity-search/create_task', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.lev8.com/v1/entity-search/create_task"

payload = {
    "entity_type": "company",
    "objective": "AI startups that raised Series A in 2024",
    "limit": 20,
    "enable_web_search": False,
    "enrich_fields": ["funding stage", "headcount"],
    "dedup_lev8_leads": [],
    "dedup_custom_leads": []
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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"
}

Creates an Entity Search task and returns a leads_search_id for later Status and Fetch calls. Idempotency-Key is optional and can contain up to 128 characters. When omitted, Lev8 generates a key and returns it in the response Header. The complete JSON body must be at most 1 MiB; unknown fields and multiple JSON objects are rejected. For entity_type: "xiaohongshu" or entity_type: "wechat", include enable_web_search: true. Use wechat for WeChat Official Account search. Requests that omit enable_web_search or set it to false return 422 invalid_request_error. Xiaohongshu and WeChat Official Account searches usually take 1 to 2 minutes before results are ready.

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"
}

The response includes Idempotency-Key, X-Request-Id, and Cache-Control: no-store. Store both Headers and the task ID with your local job. Repeating the same body with the same API key and idempotency key returns the existing task without reserving credits again. Reusing the key with different input returns 409 idempotency_error; replaying while task creation has no stable handle returns 409 request_in_progress; replaying after its recovery window returns 409 request_expired. See Entity Search for entity types, field limits, deduplication, enrichment, and web search guidance.

Authorizations

Authorization

string

header

default:lev8_live_...

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

Optional stable key for this logical task. When omitted, lev8 generates one and returns it in the response Header.

Maximum string length: 128

Body

application/json

entity_type

enum<string>

required

Entity type to search. 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.

Available options:

person,

company,

twitter_creator,

youtube_creator,

tiktok_creator,

instagram_creator,

shopify_store,

xiaohongshu,

wechat

Example:

"company"

objective

string

required

Natural-language objective, at most 4,000 UTF-8 bytes after trimming.

Minimum string length: 1

Example:

"AI startups that raised Series A in 2024"

limit

integer

default:20

Required range: 1 <= x <= 500

Example:

20

enable_web_search

boolean

default:false

Keeps database search and additionally enables open web search mode. Required and must be true when entity_type is xiaohongshu or wechat; false or omitted returns 422 invalid_request_error. Xiaohongshu and WeChat Official Account searches usually take 1 to 2 minutes to produce results.

Example:

false

enrich_fields

string[] | null

Extra fields to return under entities[].enrich_fields, up to 20 items. Use this for descriptive attributes such as funding stage or headcount. It is not suitable for finding email addresses or phone numbers; use Contact Search for contact details.

Maximum array length: 20

Example:

["funding stage", "headcount"]

dedup_lev8_leads

string[]

Maximum array length: 100

Example:

[]

dedup_custom_leads

string[]

Maximum array length: 1000

Example:

[]

Response

Task created.

object

string

Allowed value: "entity_search_task"

leads_search_id

string

Example:

"leads_search_01JABCDEF123456789"

entity_type

enum<string>

Entity type used by the task.

Available options:

person,

company,

twitter_creator,

youtube_creator,

tiktok_creator,

instagram_creator,

shopify_store,

xiaohongshu,

wechat

Example:

"company"

objective

string

Example:

"AI startups that raised Series A in 2024"

limit

integer

Example:

20

status

string

Example:

"created"

created_at

string<date-time>

Example:

"2026-08-04T00:00:00Z"

Getting started

API reference

MCP

API behavior

Create task

Example

Response

Authorizations

Headers

Body

Response

​Example

​Response

Authorizations

Headers

Body

Response

Example

Response