Web lists

Web lists – sprawdzone listy firm, stron internetowych i społeczności. Opisz zwykłymi słowami, czego potrzebujesz – firm, stron internetowych lub społeczności – dodaj warunki, które musi spełnić każdy element, i otrzymaj listę, w której każda pozycja została sprawdzona pod kątem każdego warunku, z cytatem ze źródła potwierdzającym każde dopasowanie. Następnie uzupełnij listę potrzebnymi informacjami (model cenowy, bezpłatny okres próbny, integracje, siedziba…) i wyeksportuj ją do pliku.

Stworzone z myślą o listach leadów, mapach rynku, wyszukiwaniu partnerów oraz listach stron lub społeczności: płacisz za pozycje, które spełniają Twoje warunki, a nie za te, które przejrzeliśmy i odrzuciliśmy. W API lista jest identyfikowana przez set_id.

Web lists są włączane dla klucza na życzenie: napisz na support@omev.be. Wyniki są rozliczane ze zwykłego salda klucza.

Cena

Co	Cena
Jedna zaakceptowana pozycja na liście	$0.0225
Jedna znaleziona wartość wzbogacenia (jedno pole dla jednej pozycji)	$0.0045

Płacisz w miarę dostarczania wyników: za każdą pozycję zaakceptowaną na listę i za każdą wartość wzbogacenia, która faktycznie została znaleziona. Odrzuceni kandydaci, wartości not_found i ponowne pobrania nie są płatne. Pozycja jest rozliczana raz na listę, także przy kontynuacjach find-more. estimate, get, results, exclude, export i cancel są bezpłatne.

Najpierw sprawdź cenę

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 to search (z target_count) lub enrich (z entity_field_values, czyli liczbą pozycji pomnożoną przez liczbę pól). Odpowiedź pokazuje maksymalną kwotę, jaka może zostać pobrana:

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

Tworzenie listy

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

Pole	Wymagane	Znaczenie
`query`	tak	czego szukasz, 5–2 000 znaków
`entity_type`	nie	co zawiera lista: `company` (domyślnie), `website` lub `community`
`criteria`	nie	do 8 warunków, każdy `description` do 300 znaków; `kind` to `must` (domyślnie), `must_not` lub `should` (preferowany, niewymagany); opcjonalny `id`
`target_count`	nie	ile pozycji zaakceptować, domyślnie 25, maksymalnie 100
`scope.markets`	nie	do 5 kodów krajów, domyślnie `["US"]`
`scope.languages`	nie	do 5 języków, domyślnie `["en"]`
`idempotency_key`	nie	do 200 znaków, w treści żądania lub w nagłówku `Idempotency-Key`; ponowne użycie zwraca to samo zadanie

Odpowiedzią jest zadanie:

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

Zachowaj oba identyfikatory: job_id śledzi to uruchomienie, a set_id wskazuje listę dla find-more, exclude i export.

Śledzenie zadania

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 przyjmuje wartość queued, running lub retry_wait, a następnie jedną z completed, partial, failed, cancelled. completion_reason wyjaśnia powód zakończenia: completed, saturated (pasujących pozycji jest mniej, niż zamówiono), deadline_reached, budget_exhausted, cancelled, failed. Sprawdzaj status co 5–10 sekund.

Aby zatrzymać zadanie, wyślij {"job_id": "osjob_…"} na /v1/sets/cancel. Pozycje zaakceptowane przed zatrzymaniem pozostają na liście.

Odczyt listy

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

Wyniki można czytać w trakcie działania zadania, więc możesz wcześnie zacząć pracę z pierwszymi pozycjami. limit to do 1 000 wierszy na wywołanie (domyślnie 100); kolejne strony pobieraj za pomocą offset.

Koperta zawiera status, completion_reason, target_count, accepted_count, rejected_count, unknown_count, coverage, saturation_reason i listę results. Każda pozycja wyszukiwania:

Pole	Znaczenie
`entity_id`	identyfikator pozycji na tej liście; używaj go do wzbogacania
`entity_type`, `name`, `domain`, `url`	czym jest: firmą, stroną internetową lub społecznością
`relevance_score`	40–100: każdy wpis spełnia wszystkie obowiązkowe warunki; wynik rośnie z liczbą spełnionych warunków pożądanych (`should`), siłą cytatów i liczbą niezależnych wyszukiwań, które go znalazły
`matched_criteria`	każdy spełniony warunek z `criterion`, `status`, `source_url`, dosłownym cytatem `evidence` (do 200 znaków) i krótkim `reason`

Najlepsze wpisy są pierwsze, według relevance_score.

Więcej wyników, import, wykluczenia

/v1/sets/find-more z {"set_id": "oset_…", "additional": 25} uruchamia nowe zadanie, które dodaje do additional pozycji (1–100) do tej samej listy, pomijając wszystkie pozycje, które już się na niej znajdują. Lista zawiera maksymalnie 100 zaakceptowanych pozycji.
/v1/sets/import z {"set_id": "oset_…", "items": ["example.com", …]} sprawdza Twoje własne adresy URL lub domeny (do 1 000) pod kątem warunków listy. Elementy, które je spełniają, trafiają na listę i są rozliczane jako zaakceptowane pozycje.
/v1/sets/exclude z {"set_id": "oset_…", "kind": "domain", "value": "example.com"} wyklucza pozycję z kolejnych uruchomień tej listy. kind to domain, entity, url_prefix lub list.

Wzbogacanie listy

Dodawaj informacje do pozycji, które już masz, lub do dowolnej publicznej strony internetowej.

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

Pole	Wymagane	Znaczenie
`targets`	tak	do 1 000 celów, każdy w postaci `{"entity_id": "…"}` lub `{"url": "https://…"}`
`fields`	tak	do 10 pól; iloczyn celów i pól nie może przekroczyć 500 na zadanie
`idempotency_key`	nie	tak jak przy wyszukiwaniu

Gotowe pola: company_description, product_category, pricing_start, pricing_model, has_free_trial, has_public_api, founding_year, headquarters_country, supported_integrations, primary_platforms.

Pole własne ma postać {"field": "<name>", "instruction": "<up to 500 characters>", "output_type": "string"}; output_type to string, number, boolean, string_list lub object. Profile kupujących, konkurenci, zapytania kupujących, społeczności, problemy klientów i tematy odbiorców nie są polami wzbogacenia: zamów zamiast tego raport o firmie lub raport domeny.

W results każda pozycja zawiera fields, a każde pole ma status (found, not_found, unavailable, error), value i evidence. false to prawdziwa znaleziona odpowiedź. Płatne są tylko wartości found.

Profile firm nie są już częścią Web lists: wywołanie /v1/sets/intelligence zwraca 410, a wyniki wcześniej zakończonych zadań pozostają dostępne przez /v1/sets/results.

Eksport listy do pliku

Eksport jest bezpłatny i wymaga dwóch wywołań. Najpierw utwórz eksport; format to csv (domyślnie), jsonl lub 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"}

Następnie pobierz plik, podając 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

Odpowiedzią jest sam plik jako załącznik o nazwie <set_id>.<format>: CSV (text/csv), JSON Lines (application/x-ndjson, jedna pozycja w wierszu) lub JSON (application/json, pozycje w polu results). Kolumny CSV: entity_id, entity_type, name, domain, url, relevance_score, matched_criteria (tablica JSON spełnionych warunków z dowodami).

Dalej jest po jednej kolumnie na każde pole wzbogacenia zamówione dla listy, w tej samej kolejności: znaleziona wartość (yes/no dla pól typu tak/nie, elementy listy rozdzielone ; ), pusta komórka, jeśli wartości nie znaleziono. W JSON i JSON Lines te same wartości są w polu fields. Plik obejmuje też strony wzbogacone bez wyszukiwania.

Błędy

Kod	Kiedy
`400`	nieprawidłowy JSON, pole poza zakresem, nieprawidłowy warunek lub nieobsługiwany `entity_type`; treść żądania jest ograniczona do 256 KiB
`401`	brak klucza API lub klucz nieprawidłowy
`403`	klucz nie może używać tego produktu
`404`	nieznane zadanie lub lista albo należące do innego konta
`404 EXPORT_NOT_FOUND`	nieznany eksport albo eksport innego konta
`409 IDEMPOTENCY_CONFLICT`	`idempotency_key` został już użyty z inną treścią żądania
`410`	wycofane wywołanie `/v1/sets/intelligence`
`429`	zbyt wiele żądań lub zbyt wiele zadań w kolejce; spróbuj ponownie po krótkiej przerwie

Wspólny format i wskazówki dotyczące ponawiania prób znajdziesz w Błędy.

Cena​

Najpierw sprawdź cenę​

Tworzenie listy​

Śledzenie zadania​

Odczyt listy​

Więcej wyników, import, wykluczenia​

Wzbogacanie listy​

Eksport listy do pliku​

Błędy​