Web lists

Web lists — перевірені списки компаній, сайтів і спільнот. Опишіть звичайними словами, що вам потрібно — компанії, сайти чи спільноти, — додайте умови, яким має відповідати кожен запис, і отримайте список, у якому кожен запис перевірено на відповідність усім умовам, із цитатою з джерела, що підтверджує кожен збіг. Потім доповніть список потрібними фактами (модель ціноутворення, безкоштовний пробний період, інтеграції, штаб-квартира…) і вивантажте його у файл.

Створено для списків лідів, карт ринку, пошуку партнерів і добірок сайтів чи спільнот: ви платите за записи, які пройшли ваші умови, а не за ті, які ми переглянули й відхилили. В API список має ідентифікатор set_id.

Web lists вмикаються для ключа на запит: напишіть на support@omev.be. Результати списуються зі звичайного балансу ключа.

Ціна

Що	Ціна
Один прийнятий запис у списку	$0.0225
Одне знайдене значення збагачення (одне поле для одного запису)	$0.0045

Ви платите в міру отримання результатів: за кожен запис, прийнятий до списку, і за кожне значення збагачення, яке справді знайдено. Відхилені кандидати, значення not_found і повторні завантаження не оплачуються. Запис оплачується один раз на список, зокрема з урахуванням продовжень find-more. estimate, get, results, exclude, export і cancel безкоштовні.

Спочатку дізнайтеся ціну

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 має значення search (разом із target_count) або enrich (разом із entity_field_values, тобто кількістю записів, помноженою на кількість полів). Відповідь показує максимальну суму, яку може бути списано:

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

Створення списку

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

Поле	Обов'язкове	Значення
query	так	що ви шукаєте, 5–2 000 символів
entity_type	ні	що містить список: company (за замовчуванням), website або community
criteria	ні	до 8 умов, кожен description до 300 символів; kind має значення must (за замовчуванням), must_not або should (бажано, але не обов'язково); необов'язковий id
target_count	ні	скільки записів прийняти, за замовчуванням 25, максимум 100
scope.markets	ні	до 5 кодів країн, за замовчуванням ["US"]
scope.languages	ні	до 5 мов, за замовчуванням ["en"]
idempotency_key	ні	до 200 символів, у тілі запиту або в заголовку Idempotency-Key; повторне надсилання повертає те саме завдання

Відповідь — це завдання:

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

Збережіть обидва ідентифікатори: job_id стосується цього запуску, а set_id позначає список для find-more, exclude та export.

Відстеження завдання

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 спочатку має значення queued, running або retry_wait, а потім одне з completed, partial, failed, cancelled. completion_reason пояснює причину завершення: completed, saturated (відповідних записів існує менше, ніж ви запитали), deadline_reached, budget_exhausted, cancelled, failed. Опитуйте статус кожні 5–10 секунд.

Щоб зупинити завдання, надішліть {"job_id": "osjob_…"} на /v1/sets/cancel. Записи, прийняті до зупинки, залишаються в списку.

Читання списку

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

Результати можна читати, поки завдання ще виконується, тож ви можете почати роботу з першими записами заздалегідь. limit — до 1 000 рядків за виклик (за замовчуванням 100); для посторінкового читання використовуйте offset.

Обгортка містить status, completion_reason, target_count, accepted_count, rejected_count, unknown_count, coverage, saturation_reason і список results. Кожен запис пошуку:

Поле	Значення
entity_id	запис у цьому списку; використовуйте для збагачення
entity_type, name, domain, url	що це: компанія, сайт або спільнота
relevance_score	40–100: кожен запис виконує всі обов'язкові умови; оцінка зростає з кількістю виконаних бажаних умов (should), переконливістю цитат і кількістю незалежних пошуків, що його знайшли
matched_criteria	кожна виконана умова з criterion, status, source_url, дослівною цитатою evidence (до 200 символів) і коротким поясненням reason

Найкращі записи йдуть першими, за relevance_score.

Пошук додаткових записів, імпорт, виключення

• /v1/sets/find-more з {"set_id": "oset_…", "additional": 25} запускає нове завдання, яке додає до additional записів (1–100) до того самого списку, пропускаючи всі записи, які вже в ньому є. Список містить не більше 100 прийнятих записів.
• /v1/sets/import з {"set_id": "oset_…", "items": ["example.com", …]} перевіряє ваші власні URL-адреси або домени (до 1 000) на відповідність умовам списку. Елементи, які пройшли перевірку, потрапляють до списку й оплачуються як прийняті записи.
• /v1/sets/exclude з {"set_id": "oset_…", "kind": "domain", "value": "example.com"} не допускає запис до наступних запусків цього списку. kind має значення domain, entity, url_prefix або list.

Збагачення списку

Додавайте факти до записів, які у вас уже є, або до будь-якого публічного сайту.

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

Поле	Обов'язкове	Значення
targets	так	до 1 000 цілей, кожна у вигляді {"entity_id": "…"} або {"url": "https://…"}
fields	так	до 10 полів; добуток цілей на поля не може перевищувати 500 на завдання
idempotency_key	ні	так само, як для пошуку

Готові поля: company_description, product_category, pricing_start, pricing_model, has_free_trial, has_public_api, founding_year, headquarters_country, supported_integrations, primary_platforms.

Власне поле має вигляд {"field": "<name>", "instruction": "<up to 500 characters>", "output_type": "string"}; output_type має значення string, number, boolean, string_list або object. Профілі покупців, конкуренти, пошукові запити покупців, спільноти, больові точки та теми аудиторії не є полями збагачення: для них замовте аналітичну довідку про компанію або звіт за доменом.

У results кожен запис містить fields, а кожне поле має status (found, not_found, unavailable, error), value і evidence. false — це справжня знайдена відповідь. Оплачуються лише значення found.

Профілі компаній більше не входять до Web lists: виклик /v1/sets/intelligence повертає 410, а результати завдань, завершених раніше, і далі доступні через /v1/sets/results.

Вивантаження списку у файл

Вивантаження безкоштовне й займає два виклики. Спершу створіть вивантаження; format — csv (за замовчуванням), jsonl або 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"}

Потім завантажте файл за 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

Відповідь — сам файл як вкладення з назвою <set_id>.<format>: CSV (text/csv), JSON Lines (application/x-ndjson, один запис на рядок) або JSON (application/json, записи в полі results). Колонки CSV: entity_id, entity_type, name, domain, url, relevance_score, matched_criteria (JSON-масив виконаних умов із доказами).

Далі йде по одній колонці на кожне поле збагачення, яке ви замовили для списку, у тому ж порядку: знайдене значення (yes/no для полів «так чи ні», елементи списку через ; ), порожня клітинка, якщо значення не знайдено. У JSON і JSON Lines ті самі значення лежать у полі fields. Сайти, які ви збагатили без пошуку, теж потрапляють у файл.

Помилки

Код	Коли
400	невалідний JSON, поле поза допустимими межами, невалідна умова або непідтримуваний entity_type; тіло запиту обмежене 256 KiB
401	ключ API відсутній або недійсний
403	ключ не може використовувати цей продукт
404	невідоме завдання чи список або такі, що належать іншому обліковому запису
404 EXPORT_NOT_FOUND	невідоме вивантаження або вивантаження іншого облікового запису
409 IDEMPOTENCY_CONFLICT	idempotency_key уже використано з іншим тілом запиту
410	застарілий виклик /v1/sets/intelligence
429	забагато запитів або забагато завдань у черзі; повторіть спробу після короткої паузи

Загальний формат і поради щодо повторних спроб див. у розділі Помилки.