Lookup

POST /v2/lookup esegue una ricerca web in una di sei categorie e restituisce un elenco di risultati piatto e neutrale rispetto al provider. Imposta perceive_top e renderizza anche i primi N URL dei risultati in un browser reale, così un agente ottiene la pagina dei risultati del motore di ricerca (SERP) e il contenuto della pagina dietro ogni risultato in un unico viaggio di andata e ritorno. È la risposta di EnConvert a Firecrawl /search: una sola chiamata dove altrimenti dovresti raggiungere una API di ricerca, analizzarne i risultati e poi distribuire uno scraper.

Oggi è supportato da Serper. La richiesta e la risposta parlano un vocabolario di ricerca neutrale — category, country, locale, time_filter — così un futuro cambio di provider non altera il contratto su cui scrivi il codice.

Ecco la chiamata utile più piccola. Invia una query, ottieni i principali risultati web:

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

La risposta è un elenco di risultati piatto più la provenienza per la correlazione con il supporto:

{
    "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": []
}

Vale la pena segnalarlo subito. /v2/lookup è un endpoint V2 con il proprio contatore di quota, lookup_queries, separato dalle conversioni V1 e dal contatore perceive. I piani di conversione V1 non includono le query di lookup — serve un piano che includa V2 per chiamarlo. Consulta la pagina dei prezzi per le quote per fascia e la panoramica V2 per come si relazionano i contatori V2.

Endpoint

/v2/lookup è un endpoint a chiamata singola — non c'è un percorso separato di stato o di recupero. Quando auto-percepisci, ogni pagina renderizzata diventa un'operazione perceive di prima classe con il proprio operation_id, che puoi recuperare in seguito tramite GET /v2/perceive/{operation_id}.

Content-Type: application/json.

Autenticazione

Autenticati con una chiave privata nell'header X-API-Key per le chiamate server-to-server. È il percorso usato negli esempi qui sotto.

X-API-Key: sk_live_your_private_key

Funzionano anche le chiavi pubbliche con un token bearer JWT, usando lo stesso flusso di ogni altro endpoint — genera un token con la tua chiave pk_, poi invialo come Authorization: Bearer <token>. Il flusso completo, incluso il blocco del dominio e il refresh del token, è in la guida all'autenticazione.

Ogni chiave API porta con sé un allowlist di endpoint consentiti. Se /v2/lookup non è nell'elenco della chiave, la richiesta viene rifiutata con 403.

Come funziona lookup

Una richiesta esegue una ricerca con il provider e — solo se lo richiedi — renderizza poi i principali risultati.

1. Controllo della quota. Prima di qualsiasi addebito, il gestore verifica il contatore lookup_queries per il tuo piano. Un piano disabilitato o una quota mensile esaurita vengono rifiutati con 402, così non viene addebitato nulla in caso di rifiuto.
2. Ricerca. La query va al provider di ricerca (oggi Serper) sull'endpoint per la tua category. Recency, country, locale, location, dimensione della pagina e autocorrect si mappano sui parametri del provider.
3. Normalizzazione. Ogni risultato del provider viene appiattito in un LookupResult neutrale — title, url, snippet, position — e gli extra specifici della categoria finiscono in extra, così il contratto non aggiunge mai una colonna per ogni stranezza del provider.
4. Addebito e audit. La ricerca è riuscita, quindi viene consumato un lookup_queries e viene scritta una riga di audit ch_lookup_queries. L'id della riga torna come lookup_id per la correlazione con il supporto.
5. Auto-perceive (facoltativo). Se perceive_top > 0, i primi N URL dei risultati vengono renderizzati uno alla volta tramite il singleton condiviso headless Chrome — la stessa pipeline di l'endpoint perceive. Ogni render è un'operazione /v2/perceive completa: il proprio decremento di quota, la propria riga di operazione, il proprio operation_id. Le richieste di auto-perceive producono solo Markdown — niente screenshot, PDF o estrazione LLM.

L'auto-perceive è best-effort. Un singolo URL che fallisce, o la quota perceive che si esaurisce a metà strada, degrada a un avviso e restituisce comunque i risultati della ricerca — la SERP è il prodotto principale qui, quindi un problema di percezione non affonda mai l'intera chiamata.

Parametri della richiesta

Query e categoria

Targeting e recency

Paginazione

Auto-perceive

Categorie

Ogni categoria raggiunge un endpoint diverso del provider e mostra una forma di risultato leggermente diversa. I campi universali (title, url, snippet, position) sono sempre tipizzati; i campi specifici della categoria finiscono in extra.

Vale la pena segnalare: per images e maps, url può essere null per un dato risultato quando il provider non restituisce alcun link navigabile. L'auto-perceive salta qualsiasi risultato il cui url è null, quindi un perceive_top di 5 su una SERP con due risultati senza URL percepisce al massimo tre pagine.

Risposta

L'endpoint omette i campi null, quindi un risultato web minimale porta solo i campi effettivamente popolati.

LookupResult

Leggere i risultati dell'auto-perceive

Quando invii perceive_top, scorri i risultati e controlla il campo perceive — è presente solo sui risultati che sono stati percepiti, e solo quando il loro render è riuscito. Il Markdown di ciascuno risiede dietro un URL di download pre-firmato (un link firmato a breve scadenza all'object storage) sotto perceive.outputs.markdown.url, lo stesso di una chiamata perceive diretta.

{
    "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": []
}

Quegli URL firmati scadono dopo 15 minuti. Per scaricare una pagina percepita in seguito, recupera di nuovo la sua operazione con GET /v2/perceive/{operation_id} usando l'id da perceive_operation_ids — questo rifirma gli URL e non ri-renderizza, quindi non costa quota. Vedi la sezione recupero di perceive per i dettagli.

Esempi di codice

curl — ricerca web

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 — notizie recenti, localizzate

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 — ricerca più auto-perceive dei primi 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);
}

Se chiami EnConvert da Claude, Cursor o un altro client Model Context Protocol (MCP), la capacità di ricerca è esposta come uno strumento — vedi la pagina del server MCP.

Gating del piano

Le query di lookup sono misurate sul proprio contatore, lookup_queries, separato dalle conversioni V1 e dal contatore perceive che usa l'endpoint perceive. I piani di conversione V1 non includono alcuna quota di lookup; serve un piano che includa V2.

Su una chiamata di lookup vengono addebitate due cose in modo indipendente:

Quindi una chiamata con perceive_top: 3 consuma un lookup_queries e fino a tre perceive_operations. Se la tua quota perceive si esaurisce a metà del ciclo, la ricerca restituisce comunque — l'auto-perceive si ferma semplicemente al limite e lo annota in warnings, invece di far fallire l'intera richiesta.

Le quote per fascia per entrambi i contatori si trovano su la pagina dei prezzi; sono configurate per piano, non codificate in modo fisso nell'endpoint. (Al momento della scrittura, il piano Free predefinito porta 25 lookup_queries e 50 perceive_operations al mese.)

Risposte di errore

Il gestore non riporta mai al client il testo grezzo del provider — i dettagli del provider e di SSRF restano nei log del server, e il client riceve un messaggio pulito e generico.

Un auto-perceive fallito non solleva mai un errore proprio — finisce in warnings e la chiamata risponde comunque 200. Il riferimento completo dei codici di stato è in la guida ai codici di errore.

Limiti