Lookup

POST /v2/lookup führt eine Websuche in einer von sechs Kategorien aus und liefert eine flache, anbieterneutrale Ergebnisliste zurück. Setze perceive_top, dann werden zusätzlich die Top-N-Ergebnis-URLs in einem echten Browser gerendert, sodass ein Agent die Suchmaschinen-Ergebnisseite (SERP) und den Seiteninhalt hinter jedem Treffer in einem einzigen Roundtrip erhält. Es ist EnConverts Antwort auf Firecrawl /search: ein Aufruf, wo du sonst eine Search-API ansprechen, ihre Ergebnisse parsen und dann einen Scraper auffächern würdest.

Serper steckt heute dahinter. Request und Response sprechen ein neutrales Suchvokabular — category, country, locale, time_filter — sodass ein künftiger Anbieterwechsel den Vertrag, gegen den du programmierst, nicht ändert.

Hier ist der kleinste nützliche Aufruf. Sende eine Query, erhalte die obersten Webergebnisse zurück:

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "headless chrome pdf rendering"
  }'

Die Response ist eine flache Ergebnisliste plus Provenienz für die Support-Korrelation:

{
    "lookup_id": 81423,
    "query": "headless chrome pdf rendering",
    "category": "web",
    "total": 10,
    "results": [
        {
            "title": "Generate PDFs with headless Chrome",
            "url": "https://example.com/guide/chrome-pdf",
            "snippet": "Render a page and print it to PDF...",
            "position": 1
        },
        {
            "title": "Print to PDF — Chrome DevTools Protocol",
            "url": "https://example.dev/cdp/print-to-pdf",
            "snippet": "Page.printToPDF returns base64 PDF data...",
            "position": 2
        }
    ],
    "perceive_top": 0,
    "perceive_operation_ids": [],
    "credits": 1,
    "cost_cents": 0.06,
    "warnings": []
}

Gleich vorweg erwähnenswert. /v2/lookup ist ein V2-Endpunkt mit eigenem Quota-Zähler, lookup_queries, getrennt von V1-Konvertierungen und vom Perceive-Zähler. V1-Konvertierungspläne enthalten keine Lookup-Queries — du brauchst einen V2-inklusiven Plan, um ihn aufzurufen. Siehe die Preisseite für die Kontingente pro Stufe und die V2-Übersicht, wie die V2-Zähler zusammenhängen.

Endpunkte

/v2/lookup ist ein Single-Call-Endpunkt — es gibt keinen separaten Status- oder Abrufpfad. Beim Auto-Perceive wird jede gerenderte Seite zu einer vollwertigen Perceive-Operation mit eigener operation_id, die du später über GET /v2/perceive/{operation_id} erneut abrufen kannst.

Content-Type: application/json.

Authentifizierung

Authentifiziere dich mit einem privaten Schlüssel im X-API-Key-Header für Server-zu-Server-Aufrufe. Diesen Weg nutzen die Beispiele unten.

X-API-Key: sk_live_your_private_key

Öffentliche Schlüssel mit einem JWT-Bearer-Token funktionieren ebenfalls und nutzen denselben Ablauf wie jeder andere Endpunkt — erzeuge ein Token mit deinem pk_-Schlüssel und sende es dann als Authorization: Bearer <token>. Der vollständige Ablauf, inklusive Domain-Locking und Token-Refresh, steht in der Authentifizierungs-Anleitung.

Jeder API-Schlüssel trägt eine Allowlist erlaubter Endpunkte. Wenn /v2/lookup nicht auf der Liste des Schlüssels steht, wird der Request mit 403 abgewiesen.

So funktioniert Lookup

Ein Request führt eine Anbietersuche aus und — nur wenn du es anforderst — rendert anschließend die obersten Ergebnisse.

1. Quota-Gate. Bevor irgendetwas abgerechnet wird, prüft der Handler den lookup_queries-Zähler deines Plans. Ein deaktivierter Plan oder ein ausgeschöpftes Monatskontingent wird mit 402 abgewiesen, sodass bei einer Ablehnung nichts berechnet wird.
2. Suche. Die Query geht an den Suchanbieter (heute Serper) auf dem Endpunkt für deine category. Aktualität, Land, Locale, Standort, Seitengröße und Autokorrektur werden auf die Parameter des Anbieters abgebildet.
3. Normalisieren. Jeder Anbietertreffer wird in ein neutrales LookupResult abgeflacht — title, url, snippet, position — und die kategoriespezifischen Extras landen in extra, sodass der Vertrag nie eine Spalte pro Anbieter-Eigenheit dazubekommt.
4. Abrechnen und auditieren. Die Suche war erfolgreich, also wird ein lookup_queries verbraucht und eine ch_lookup_queries-Audit-Zeile geschrieben. Die Zeilen-ID kommt als lookup_id für die Support-Korrelation zurück.
5. Auto-Perceive (optional). Wenn perceive_top > 0, werden die Top-N-Ergebnis-URLs eine nach der anderen durch das gemeinsame Headless-Chrome-Singleton gerendert — dieselbe Pipeline wie der Perceive-Endpunkt. Jedes Rendering ist eine vollständige /v2/perceive-Operation: eigener Quota-Abzug, eigene Operations-Zeile, eigene operation_id. Auto-Perceive fordert nur Markdown an — keinen Screenshot, kein PDF, keine LLM-Extraktion.

Auto-Perceive ist Best-Effort. Eine einzelne URL, die fehlschlägt, oder ein mitten im Durchlauf erschöpftes Perceive-Kontingent stuft auf eine Warnung herab und liefert trotzdem die Suchergebnisse — die SERP ist hier das primäre Produkt, ein Wahrnehmungsproblem versenkt also nie den gesamten Aufruf.

Request-Parameter

Query und Kategorie

Targeting und Aktualität

Pagination

Auto-Perceive

Kategorien

Jede Kategorie spricht einen anderen Anbieter-Endpunkt an und liefert eine leicht abweichende Ergebnisform. Die universellen Felder (title, url, snippet, position) sind stets typisiert; kategoriespezifische Felder landen in extra.

Erwähnenswert: Bei images und maps kann url für einen bestimmten Treffer null sein, wenn der Anbieter keinen navigierbaren Link zurückgibt. Auto-Perceive überspringt jedes Ergebnis, dessen url null ist, sodass ein perceive_top von 5 auf einer SERP mit zwei URL-losen Treffern höchstens drei Seiten perceived.

Response

Der Endpunkt lässt null-Felder weg, sodass ein minimales web-Ergebnis nur die Felder trägt, die tatsächlich befüllt sind.

LookupResult

Auto-Perceive-Ergebnisse lesen

Wenn du perceive_top sendest, gehe die Ergebnisse durch und prüfe auf das perceive-Feld — es ist nur auf den Ergebnissen vorhanden, die perceived wurden, und nur, wenn ihr Rendering erfolgreich war. Das Markdown für jedes liegt hinter einer vorsignierten Download-URL (ein kurzlebiger, signierter Link zum Objektspeicher) unter perceive.outputs.markdown.url, genauso wie bei einem direkten Perceive-Aufruf.

{
    "lookup_id": 81910,
    "query": "react server components data fetching",
    "category": "web",
    "total": 10,
    "results": [
        {
            "title": "Data fetching with RSC",
            "url": "https://example.com/rsc/data",
            "snippet": "Fetch on the server, stream to the client...",
            "position": 1,
            "perceive": {
                "operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
                "status": "completed",
                "url": "https://example.com/rsc/data",
                "outputs": {
                    "markdown": {
                        "url": "https://spaces.example.com/...signed...",
                        "size_bytes": 7421,
                        "content_type": "text/markdown; charset=utf-8",
                        "expires_in": 900
                    }
                },
                "cost_cents": 0.0,
                "duration_ms": 5840
            }
        }
    ],
    "perceive_top": 1,
    "perceive_operation_ids": [
        "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7"
    ],
    "credits": 1,
    "cost_cents": 0.06,
    "warnings": []
}

Diese signierten URLs laufen nach 15 Minuten ab. Um eine perceivete Seite später herunterzuladen, rufe ihre Operation erneut mit GET /v2/perceive/{operation_id} ab, unter Verwendung der ID aus perceive_operation_ids — das signiert die URLs neu und rendert nicht erneut, kostet also kein Kontingent. Siehe den Perceive-Abruf-Abschnitt für die Details.

Codebeispiele

curl — Websuche

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "open source vector database",
    "num_results": 20
  }'

curl — aktuelle Nachrichten, lokalisiert

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "rbi monetary policy",
    "category": "news",
    "country": "in",
    "locale": "en",
    "time_filter": "week"
  }'

curl — Suche plus Auto-Perceive der Top 3

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "langchain retrieval augmented generation",
    "perceive_top": 3
  }'

Python

import requests

response = requests.post(
    "https://api.enconvert.com/v2/lookup",
    headers={"X-API-Key": "sk_live_your_private_key"},
    json={
        "query": "langchain retrieval augmented generation",
        "perceive_top": 3,
    },
)
response.raise_for_status()
data = response.json()

# Pull the Markdown of every result that was perceived
for result in data["results"]:
    perceived = result.get("perceive")
    if not perceived:
        continue
    markdown_url = perceived["outputs"]["markdown"]["url"]
    page_text = requests.get(markdown_url).text
    print(result["url"], len(page_text), "chars")

for note in data["warnings"]:
    print("warning:", note)

Node.js

const res = await fetch("https://api.enconvert.com/v2/lookup", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_live_your_private_key"
    },
    body: JSON.stringify({
        query: "langchain retrieval augmented generation",
        perceive_top: 3
    })
});

const data = await res.json();

// Pull the Markdown of every result that was perceived
for (const result of data.results) {
    if (!result.perceive) continue;
    const markdownUrl = result.perceive.outputs.markdown.url;
    const pageText = await fetch(markdownUrl).then(r => r.text());
    console.log(result.url, pageText.length, "chars");
}

for (const note of data.warnings) {
    console.log("warning:", note);
}

Wenn du EnConvert aus Claude, Cursor oder einem anderen Model-Context-Protocol- (MCP-)Client aufrufst, wird die Suchfähigkeit als Tool bereitgestellt — siehe die MCP-Server-Seite.

Plan-Gating

Lookup-Queries werden auf einem eigenen Zähler gemessen, lookup_queries, getrennt von V1-Konvertierungen und von dem Perceive-Zähler, den der Perceive-Endpunkt verwendet. V1-Konvertierungspläne enthalten kein Lookup-Kontingent; du brauchst einen V2-inklusiven Plan.

Zwei Dinge werden bei einem Lookup-Aufruf unabhängig abgerechnet:

Ein Aufruf mit perceive_top: 3 verbraucht also ein lookup_queries und bis zu drei perceive_operations. Wenn dein Perceive-Kontingent mitten im Loop erschöpft ist, liefert die Suche trotzdem — Auto-Perceive stoppt einfach an der Grenze und vermerkt es in warnings, anstatt den gesamten Request scheitern zu lassen.

Die Kontingente pro Stufe für beide Zähler stehen auf der Preisseite; sie werden pro Plan konfiguriert, nicht im Endpunkt fest verdrahtet. (Zum Zeitpunkt des Schreibens trägt der Free-Plan standardmäßig 25 lookup_queries und 50 perceive_operations pro Monat.)

Fehler-Responses

Der Handler gibt nie rohen Anbietertext an den Client zurück — Anbieter- und SSRF-Details bleiben in den Server-Logs, und der Client erhält eine saubere, generische Meldung.

Ein fehlschlagendes Auto-Perceive löst nie einen eigenen Fehler aus — es landet in warnings, und der Aufruf antwortet trotzdem mit 200. Die vollständige Statuscode-Referenz steht in der Fehlercodes-Anleitung.

Limits