Recherche (Lookup)

POST /v2/lookup exécute une recherche web dans l'une des six catégories et renvoie une liste de résultats plate, neutre vis-à-vis du fournisseur. Définissez perceive_top et il effectue en plus le rendu des N premières URL de résultat dans un vrai navigateur, de sorte qu'un agent obtient la page de résultats du moteur de recherche (SERP) et le contenu de la page derrière chaque résultat en un seul aller-retour. C'est la réponse d'EnConvert à Firecrawl /search : un seul appel là où vous appelleriez sinon une API de recherche, analyseriez ses résultats, puis déploieriez un scraper en éventail.

Serper l'alimente aujourd'hui. La requête et la réponse parlent un vocabulaire de recherche neutre — category, country, locale, time_filter — de sorte qu'un futur changement de fournisseur ne modifie pas le contrat sur lequel vous codez.

Voici le plus petit appel utile. Envoyez une requête, récupérez les meilleurs résultats 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 réponse est une liste de résultats plate plus la provenance pour la corrélation côté support :

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

À signaler d'emblée. /v2/lookup est un endpoint V2 doté de son propre compteur de quota, lookup_queries, distinct des conversions V1 et du compteur perceive. Les plans de conversion V1 n'incluent pas de requêtes lookup — il vous faut un plan incluant la V2 pour l'appeler. Consultez la page de tarification pour les allocations par palier, et l'aperçu V2 pour comprendre comment les compteurs V2 sont liés entre eux.

Endpoints

/v2/lookup est un endpoint à appel unique — il n'existe pas de chemin distinct de statut ou de récupération. Lorsque vous auto-percevez, chaque page rendue devient une opération perceive de premier ordre dotée de son propre operation_id, que vous pouvez récupérer ultérieurement via GET /v2/perceive/{operation_id}.

Content-Type : application/json.

Authentification

Authentifiez-vous avec une clé privée dans l'en-tête X-API-Key pour les appels serveur à serveur. C'est la voie qu'utilisent les exemples ci-dessous.

X-API-Key: sk_live_your_private_key

Les clés publiques avec un jeton bearer JWT fonctionnent aussi, selon le même flux que tout autre endpoint — générez un jeton avec votre clé pk_, puis envoyez-le sous la forme Authorization: Bearer <token>. Le flux complet, y compris le verrouillage de domaine et le rafraîchissement du jeton, figure dans le guide d'authentification.

Chaque clé d'API porte une liste blanche d'endpoints autorisés. Si /v2/lookup n'est pas sur la liste de la clé, la requête est rejetée avec 403.

Comment fonctionne lookup

Une requête exécute une recherche fournisseur, et — seulement si vous le demandez — effectue ensuite le rendu des meilleurs résultats.

1. Contrôle de quota. Avant toute facturation, le gestionnaire vérifie le compteur lookup_queries pour votre plan. Un plan désactivé ou un quota mensuel épuisé est rejeté avec 402, de sorte que rien n'est facturé en cas de rejet.
2. Recherche. La requête part vers le fournisseur de recherche (Serper aujourd'hui) sur l'endpoint correspondant à votre category. Récence, pays, locale, localisation, taille de page et autocorrection sont mappés sur les paramètres du fournisseur.
3. Normalisation. Chaque résultat du fournisseur est aplati en un LookupResult neutre — title, url, snippet, position, et les extras propres à la catégorie atterrissent dans extra, de sorte que le contrat n'ajoute jamais une colonne par particularité de fournisseur.
4. Facturation et audit. La recherche a réussi, donc un lookup_queries est consommé et une ligne d'audit ch_lookup_queries est écrite. L'identifiant de la ligne revient sous lookup_id pour la corrélation côté support.
5. Auto-perception (optionnelle). Si perceive_top > 0, les N premières URL de résultat sont rendues une par une via le singleton headless Chrome partagé — le même pipeline que l'endpoint perceive. Chaque rendu est une opération /v2/perceive complète : son propre décrément de quota, sa propre ligne d'opération, son propre operation_id. Les requêtes d'auto-perception ne demandent que du Markdown — pas de capture d'écran, de PDF ni d'extraction LLM.

L'auto-perception est au mieux. Une URL isolée qui échoue, ou le quota perceive qui s'épuise en cours de route, se dégrade en avertissement et renvoie tout de même les résultats de recherche — la SERP est ici le produit principal, donc un problème de perception ne fait jamais couler l'appel entier.

Paramètres de requête

Requête et catégorie

Ciblage et récence

Pagination

Auto-perception

Catégories

Chaque catégorie atteint un endpoint fournisseur différent et fait apparaître une forme de résultat légèrement différente. Les champs universels (title, url, snippet, position) sont toujours typés ; les champs propres à la catégorie atterrissent dans extra.

À signaler : pour images et maps, url peut être null pour un résultat donné lorsque le fournisseur ne renvoie aucun lien navigable. L'auto-perception ignore tout résultat dont l'url est null, de sorte qu'un perceive_top de 5 sur une SERP comptant deux résultats sans URL perçoit au plus trois pages.

Réponse

L'endpoint omet les champs null, de sorte qu'un résultat web minimal ne porte que les champs réellement renseignés.

LookupResult

Lire les résultats d'auto-perception

Lorsque vous envoyez perceive_top, parcourez les résultats et vérifiez la présence du champ perceive — il n'est présent que sur les résultats qui ont été perçus, et seulement lorsque leur rendu a réussi. Le Markdown de chacun se trouve derrière une URL de téléchargement pré-signée (un lien signé à courte durée de vie vers le stockage objet) sous perceive.outputs.markdown.url, comme pour un appel perceive direct.

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

Ces URL signées expirent au bout de 15 minutes. Pour télécharger une page perçue plus tard, récupérez à nouveau son opération avec GET /v2/perceive/{operation_id} en utilisant l'identifiant tiré de perceive_operation_ids — cela re-signe les URL et n'effectue pas de nouveau rendu, donc cela ne coûte aucun quota. Consultez la section de récupération de perceive pour les détails.

Exemples de code

curl — recherche 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 — actualités récentes, localisées

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 — recherche plus auto-perception des 3 premiers

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);
}

Si vous appelez EnConvert depuis Claude, Cursor, ou un autre client Model Context Protocol (MCP), la capacité de recherche est exposée comme un outil — voir la page du serveur MCP.

Restriction par plan

Les requêtes lookup sont décomptées sur leur propre compteur, lookup_queries, distinct des conversions V1 et du compteur perceive qu'utilise l'endpoint perceive. Les plans de conversion V1 n'incluent aucun quota lookup ; il vous faut un plan incluant la V2.

Deux choses sont facturées indépendamment lors d'un appel lookup :

Ainsi, un appel avec perceive_top: 3 consomme un lookup_queries et jusqu'à trois perceive_operations. Si votre quota perceive s'épuise en cours de boucle, la recherche renvoie tout de même — l'auto-perception s'arrête simplement à la limite et le note dans warnings, plutôt que de faire échouer toute la requête.

Les allocations par palier pour les deux compteurs figurent sur la page de tarification ; elles sont configurées par plan, pas codées en dur dans l'endpoint. (Au moment de la rédaction, le plan Free par défaut porte 25 lookup_queries et 50 perceive_operations par mois.)

Réponses d'erreur

Le gestionnaire ne renvoie jamais le texte brut du fournisseur au client — les détails du fournisseur et de la SSRF restent dans les journaux du serveur, et le client reçoit un message propre et générique.

Une auto-perception qui échoue ne lève jamais d'erreur de son propre fait — elle atterrit dans warnings et l'appel répond tout de même 200. La référence complète des codes de statut figure dans le guide des codes d'erreur.

Limites