Réponse rapide
Que renvoie l'API LLMWebSearch pour une requête ?
LLMWebSearch renvoie du JSON avec les query, created_at, credits_used et un tableau results classé. Chaque résultat a sa position, son titre, son URL, son hôte et un extrait, ainsi qu'un content_status ; quand il vaut ok, le contenu principal de la page se trouve dans content avec un word_count. Une requête avec jusqu'à 3 pages lues coûte 1 crédit, à partir de 1,20 $US/1K requêtes en octobre 2026. Sans KYC ; paiement en crypto.
Quels champs décrivent l'appel ?
Niveau supérieur d'une réponse /search.
| Champ | Type | Signification |
|---|---|---|
query | string | La requête telle que nous l'avons exécutée, après suppression des espaces |
created_at | string | Moment où la requête a été exécutée, ISO 8601 en UTC |
credits_used | integer | Ce que l'appel a coûté : 1, ou 2 quand read valait de 4 à 10 |
results | array | Résultats classés, du meilleur au moins bon, au plus max_results éléments |
Quels champs porte chaque résultat ?
Un champ que la page ou le résultat de recherche ne fournit pas est omis plutôt qu'envoyé vide.
| Champ | Type | Lorsqu'il est présent | Signification |
|---|---|---|---|
position | integer | Toujours | Rang dans la requête, à partir de 1 |
title | string | Toujours | Titre du résultat |
url | string | Toujours | Adresse de la page |
host | string | Toujours | Nom d'hôte de la page, pratique pour regrouper ou citer |
snippet | string | Toujours | Court extrait affiché par la requête |
published_at | string | Lorsque la date est connue | Date de publication indiquée par la page ou le résultat de recherche |
content_status | string | Toujours | Si la page a été lue, et sinon, pourquoi |
content | string | Lorsque content_status vaut ok | Contenu principal en Markdown ou en texte brut, coupé à max_chars |
word_count | integer | Lorsque content_status vaut ok | Mots dans l'ensemble du texte extrait, comptés avant la coupure |
target_status | integer | Avec target_refused | Le code de statut HTTP renvoyé par le site, par exemple 403 ou 429 |
Que signifie chaque content_status ?
Aucun de ces éléments ne change le prix de la requête. Ils décrivent une page, jamais l'appel entier.
content_status | Signification | Ce qu'un agent doit faire |
|---|---|---|
ok | La page a été lue ; content contient son texte principal | Utilisez-le et citez le url |
not_requested | Le résultat dépasse le nombre read | Augmentez read, ou lisez-le via /extract si nécessaire |
blocked_by_robots | Le robots.txt du site n'autorise pas notre lecteur sur cette page | Appuyez-vous sur l'extrait ou sur une autre source |
blocked_by_site_policy | Le site déclare Content-Signal: ai-input=no | Appuyez-vous sur l'extrait ou sur une autre source |
target_refused | Le site a refusé la requête ; voir target_status | Ne réessayez pas la page ; utilisez une autre source |
fetch_failed | Erreur DNS, TLS ou de connexion, ou page disparue | Essayez un autre résultat ; une nouvelle tentative ultérieure peut fonctionner |
fetch_timeout | La page n'a pas répondu dans les 15 secondes | Essayez un autre résultat ; une nouvelle tentative ultérieure peut fonctionner |
unsupported_content | Le lien pointe vers un fichier que nous ne pouvons pas convertir en texte | Utilisez l'extrait ou un autre résultat |
À quoi ressemble une réponse complète ?
L'exemple ci-dessous demandait 5 résultats avec les 4 premiers lus, il a donc coûté 2 crédits. Les résultats 1 et 3 ont été lus. Le résultat 2 appartient à un site dont le robots.txt exclut notre lecteur, le résultat 4 a refusé la requête, et le résultat 5 se situe au-delà de read. Les titres, URLs et valeurs sont illustratifs.
{
"query": "how to rotate api keys without downtime",
"created_at": "2026-10-22T10:15:04Z",
"credits_used": 2,
"results": [
{
"position": 1,
"title": "Rotating API keys",
"url": "https://docs.example.com/security/key-rotation",
"host": "docs.example.com",
"snippet": "Create a second key, deploy it everywhere, then revoke the first one.",
"published_at": "2026-09-30",
"content_status": "ok",
"content": "# Rotating API keys\n\n## Zero-downtime rotation\n\n1. Create a second key.\n2. Deploy it to every service.\n3. Revoke the old key.",
"word_count": 948
},
{
"position": 2,
"title": "Key rotation checklist",
"url": "https://blog.example.org/key-rotation-checklist",
"host": "blog.example.org",
"snippet": "Keep two keys active during the switch and alert on the old one.",
"content_status": "blocked_by_robots"
},
{
"position": 3,
"title": "Secrets management basics",
"url": "https://security.example.net/secrets-basics",
"host": "security.example.net",
"snippet": "Never commit keys to a repository.",
"content_status": "ok",
"content": "# Secrets management basics\n\n**Never** commit keys to a repository.",
"word_count": 1310
},
{
"position": 4,
"title": "Key management service guide",
"url": "https://cloud.example.com/kms-guide",
"host": "cloud.example.com",
"snippet": "Store keys in a managed vault and rotate them on a schedule.",
"content_status": "target_refused",
"target_status": 403
},
{
"position": 5,
"title": "API key best practices",
"url": "https://dev.example.com/api-key-best-practices",
"host": "dev.example.com",
"snippet": "Scope each key to one service and one environment.",
"content_status": "not_requested"
}
]
}Quels résultats reçoivent un statut de page autre que not_requested ?
Seulement les read premiers résultats, et chaque élément d'un appel /extract. Ce sont les pages que notre lecteur a réellement tentées. Tout ce qui vient après le compte de read reste not_requested, quelle que soit la réponse du site.
L'ordre ne change jamais : le lecteur travaille sur les positions 1, 2, 3, etc., jamais sur un résultat plus tardif à la place d'un précédent qui a échoué. Si un agent a besoin d'un remplacement pour une page refusée, il peut lire le résultat suivant via /extract.
À quoi ressemble une réponse extract ?
/extract renvoie credits_used et un tableau results dans l'ordre des URL envoyées. Chaque élément contient le url et un content_status ; avec ok, il ajoute title, content et word_count, et avec target_refused, il ajoute target_status. Il n'y a pas de position, host ni snippet, car aucune search n'a été lancée.
La référence extract montre un exemple complet et explique comment ses crédits sont comptés.
Comment transformer les résultats en contexte pour un modèle ?
Numérotez les sources, gardez l'URL à côté de chacune et ne transmettez que ce dont le modèle a besoin. Une mise en page compacte fonctionne bien : [1] title — url, puis le contenu de cette page, puis la source suivante. Demandez au modèle de citer avec les mêmes numéros.
Quand un résultat n'a pas de contenu, donnez plutôt son snippet au modèle en précisant qu'il s'agit seulement d'un snippet. Cela évite les réponses construites sur une page que le modèle n'a jamais vue. La page Python contient une courte boucle qui fait tout cela dans un budget de tokens.
Format de réponse : questions fréquentes
Le contenu est-il toujours en Markdown ?
Markdown par défaut. Envoyez format: "text" pour obtenir du texte brut sans balisage, par exemple quand vous comptez seulement des mots ou classez des pages. Le nom du champ reste content.
Pourquoi published_at manque-t-il sur certains résultats ?
Beaucoup de pages n'indiquent aucune date, et certains résultats de recherche n'en affichent pas non plus. Le champ est alors omis, vérifiez donc sa présence avant de l'utiliser.
De nouveaux champs peuvent-ils apparaître plus tard ?
Oui. En version 1, des champs peuvent être ajoutés, mais jamais renommés ni supprimés. Écrivez votre parseur pour qu'il ignore les champs qu'il ne connaît pas.
Le contenu est-il stocké de votre côté ?
Non. Nous n'entraînons aucun modèle sur vos requêtes ni sur ce que renvoie l'API, et nous n'ajoutons aucune règle de notre cru contre la conservation des résultats ; les droits des sites dont vous lisez les pages s'appliquent toujours. Notre journal de requêtes ne conserve qu'une courte trace de chaque appel, décrite sur la page confidentialité.