Web lists

Describe in plain words what you need — companies, websites or communities — add the conditions each one must meet, and get back a list in which every entry was checked against every condition, with a quote from the source that proves each match. Then fill the list with the facts you need (pricing model, free trial, integrations, headquarters…) and export it to a file.

Built for lead lists, market maps, partner research and lists of sites or communities: you pay for entries that pass your conditions, not for the ones we looked at and rejected. In the API a list is identified by its set_id.

Web lists are switched on for a key on request: write to support@omev.be. Results are charged to the key's usual balance.

Price

What	Price
One accepted entry in a list	$0.0225
One found enrichment value (one field for one entry)	$0.0045

You pay as results are delivered: for each entry accepted into the list and for each enrichment value that was actually found. Rejected candidates, not_found values and repeated downloads are not charged. An entry is charged once per list, including across find-more continuations. estimate, get, results, exclude, export and cancel are free.

Get a price first

curl -sS https://llmapi.omev.be/v1/sets/estimate \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation": "search", "target_count": 25}'

operation is search (with target_count) or enrich (with entity_field_values, the number of entries times the number of fields). The answer shows the maximum you can be charged:

{
  "quote": {
    "operation": "search", "currency": "USD",
    "lines": [{"kind": "accepted_entity", "unit_price_usd": "0.0225",
               "max_units": "25", "max_total_usd": "0.5625"}],
    "max_total_usd": "0.5625",
    "note": "accepted entities are charged on the accepted count, not the target"
  }
}

Build a list

curl -sS https://llmapi.omev.be/v1/sets/search \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "company",
    "query": "Podcast editing software for small businesses",
    "criteria": [
      {"description": "Offers a self-serve paid plan", "kind": "must"},
      {"description": "Has a free trial", "kind": "should"},
      {"description": "Is a freelance agency, not a software product", "kind": "must_not"}
    ],
    "target_count": 25,
    "scope": {"markets": ["US"], "languages": ["en"]},
    "idempotency_key": "acme-17-podcast-tools-2026-09"
  }'

Field	Required	Meaning
query	yes	what you are looking for, 5–2,000 characters
entity_type	no	what the list holds: company (default), website or community
criteria	no	up to 8 conditions, each description up to 300 characters; kind is must (default), must_not or should (preferred, not required); optional id
target_count	no	how many entries to accept, default 25, maximum 100
scope.markets	no	up to 5 country codes, default ["US"]
scope.languages	no	up to 5 languages, default ["en"]
idempotency_key	no	up to 200 characters, in the body or the Idempotency-Key header; repeating it returns the same job

The answer is the job:

{"schema": "sets_job_ack_v1", "job_id": "osjob_…", "operation": "search",
 "status": "queued", "hard_deadline_seconds": 600, "set_id": "oset_…", "target_count": 25}

Keep both identifiers: job_id follows this run, set_id names the list for find-more, exclude and export.

Follow the job

curl -sS https://llmapi.omev.be/v1/sets/get \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "osjob_…"}'

{"job": {"id": "osjob_…", "kind": "search", "status": "running",
         "created_at": "…", "deadline_at": "…", "completion_reason": null,
         "progress": {"processed": 12, "total_or_target": 25}}}

status is queued, running or retry_wait, then one of completed, partial, failed, cancelled. completion_reason explains the end: completed, saturated (fewer matching entries exist than you asked for), deadline_reached, budget_exhausted, cancelled, failed. Poll every 5–10 seconds.

To stop a job, send {"job_id": "osjob_…"} to /v1/sets/cancel. Entries accepted before the stop stay in the list.

Read the list

curl -sS https://llmapi.omev.be/v1/sets/results \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "osjob_…", "limit": 100, "offset": 0}'

Results are readable while the job runs, so you can start working with the first entries early. limit is up to 1,000 rows per call (default 100); page with offset.

The envelope holds status, completion_reason, target_count, accepted_count, rejected_count, unknown_count, coverage, saturation_reason and the results list. Each entry of a search:

Field	Meaning
entity_id	the entry in this list; use it for enrichment
entity_type, name, domain, url	what it is: a company, a website or a community
relevance_score	40–100: every entry meets all your required conditions; the score adds how many desirable (should) conditions it meets, how firmly the quotes prove the conditions and how many independent searches found it
matched_criteria	each met condition with criterion, status, source_url, a verbatim evidence quote (up to 200 characters) and a short reason

Entries come best first, by relevance_score.

Find more, import, exclude

• /v1/sets/find-more with {"set_id": "oset_…", "additional": 25} starts a new job that adds up to additional entries (1–100) to the same list, skipping every entry already in it. A list holds at most 100 accepted entries.
• /v1/sets/import with {"set_id": "oset_…", "items": ["example.com", …]} checks your own URLs or domains (up to 1,000) against the list's conditions. Items that pass join the list and are charged as accepted entries.
• /v1/sets/exclude with {"set_id": "oset_…", "kind": "domain", "value": "example.com"} keeps an entry out of later runs of this list. kind is domain, entity, url_prefix or list.

Enrich a list

Add facts to entries you already have, or to any public website.

curl -sS https://llmapi.omev.be/v1/sets/enrich \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [{"entity_id": "…"}, {"url": "https://example.com"}],
    "fields": [
      {"field": "pricing_model"},
      {"field": "has_free_trial"},
      {"field": "offers_white_label", "instruction": "Does the company sell a white-label version?", "output_type": "boolean"}
    ],
    "idempotency_key": "acme-17-podcast-enrich-1"
  }'

Field	Required	Meaning
targets	yes	up to 1,000 targets, each {"entity_id": "…"} or {"url": "https://…"}
fields	yes	up to 10 fields; targets × fields may not exceed 500 per job
idempotency_key	no	as for search

Ready-made fields: company_description, product_category, pricing_start, pricing_model, has_free_trial, has_public_api, founding_year, headquarters_country, supported_integrations, primary_platforms.

A custom field is {"field": "<name>", "instruction": "<up to 500 characters>", "output_type": "string"}; output_type is string, number, boolean, string_list or object. Buyer profiles, competitors, buyer queries, communities, pain points and audience themes are not enrichment fields: order a company intelligence brief or a domain report instead.

In results, each entry carries fields, and each field has status (found, not_found, unavailable, error), value and evidence. false is a real found answer. Only found values are charged.

Company profiles are no longer part of Web lists: the /v1/sets/intelligence call answers 410, and results of jobs finished earlier stay readable through /v1/sets/results.

Export a list to a file

Exporting is free and takes two calls. First create the export; format is csv (default), jsonl or json:

curl -sS https://llmapi.omev.be/v1/sets/export \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"set_id": "oset_…", "format": "csv"}'

{"export_id": "osexp_…", "format": "csv", "row_count": 25, "status": "ready"}

Then download the file with the export_id:

curl -sS https://llmapi.omev.be/v1/sets/export \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"export_id": "osexp_…"}' \
  -o list.csv

The answer is the file itself as an attachment named <set_id>.<format>: CSV (text/csv), JSON Lines (application/x-ndjson, one entry per line) or JSON (application/json, the entries under results). CSV columns: entity_id, entity_type, name, domain, url, relevance_score, matched_criteria (a JSON array of the met conditions with their evidence).

After them comes one column per enrichment field you requested for the list, in the order you asked for them: the found value (yes/no for yes-or-no fields, list items separated by ; ), empty when the value was not found. JSON and JSON Lines entries carry the same values under fields. Sites you enriched without a search are included too.

Errors

Code	When
400	invalid JSON, a field out of range, an invalid condition or an unsupported entity_type; the body is limited to 256 KiB
401	missing or invalid API key
403	the key cannot use this product
404	unknown job or list, or one that belongs to another account
404 EXPORT_NOT_FOUND	unknown export, or an export of another account
409 IDEMPOTENCY_CONFLICT	the idempotency_key was already used with a different body
410	the retired /v1/sets/intelligence call
429	too many requests or too many jobs in the queue; retry after a short pause

See Errors for the common format and retry advice.