# Format de réponse : chaque champ d'une requête, expliqué

> Format de réponse de l'API : chaque champ de /search et /extract, les valeurs de content_status et target_status, avec un exemple. Sans KYC, crypto.

- URL: https://llmwebsearch.com/fr/docs/response/
- Dernière mise à jour: 2026-10-22
- Éditeur: LLMWebSearch (https://llmwebsearch.com)

La réponse à une requête est un objet JSON : quelques champs sur l'appel, puis un tableau `results` classé. Chaque résultat indique si sa page a été lue et, le cas échéant, contient le contenu. Voici chaque champ, avec les statuts qu'un agent doit gérer.

**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.

*Réponse de POST /search (illustrative)*

```json
{
  "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](https://llmwebsearch.com/fr/docs/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](https://llmwebsearch.com/fr/docs/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é](https://llmwebsearch.com/fr/privacy/).

---

LLMWebSearch: LLMWebSearch est une API de recherche web pour agents IA qui renvoie des résultats classés avec le contenu des meilleures pages en Markdown, payée en crypto sans envoi de pièce d'identité. Les crédits prépayés à partir de 1,20 $US/1K requêtes n'expirent jamais. Sans KYC — pas de pièce d'identité, pas de selfie, pas de documents. Payez en crypto.