L’outil de récupération web permet à Claude de récupérer le contenu complet de pages web spécifiées et de documents PDF.

L’outil de récupération web est actuellement en version bêta. Pour l’activer, utilisez l’en-tête bêta web-fetch-2025-09-10 dans vos requêtes API.

Veuillez utiliser ce formulaire pour fournir des commentaires sur la qualité des réponses du modèle, l’API elle-même, ou la qualité de la documentation.

Activer l’outil de récupération web dans des environnements où Claude traite des entrées non fiables aux côtés de données sensibles pose des risques d’exfiltration de données. Nous recommandons d’utiliser cet outil uniquement dans des environnements de confiance ou lors de la manipulation de données non sensibles.

Pour minimiser les risques d’exfiltration, Claude n’est pas autorisé à construire dynamiquement des URL. Claude ne peut récupérer que les URL qui ont été explicitement fournies par l’utilisateur ou qui proviennent de résultats de recherche web ou de récupération web précédents. Cependant, il existe encore un risque résiduel qui doit être soigneusement considéré lors de l’utilisation de cet outil.

Si l’exfiltration de données est une préoccupation, considérez :

  • Désactiver entièrement l’outil de récupération web
  • Utiliser le paramètre max_uses pour limiter le nombre de requêtes
  • Utiliser le paramètre allowed_domains pour restreindre aux domaines sûrs connus

​
Modèles pris en charge

La récupération web est disponible sur :

  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 v2 (déprécié) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
Comment fonctionne la récupération web

Lorsque vous ajoutez l’outil de récupération web à votre requête API :

  1. Claude décide quand récupérer le contenu basé sur l’invite et les URL disponibles.
  2. L’API récupère le contenu textuel complet de l’URL spécifiée.
  3. Pour les PDF, l’extraction automatique de texte est effectuée.
  4. Claude analyse le contenu récupéré et fournit une réponse avec des citations optionnelles.

​
Comment utiliser la récupération web

Fournissez l’outil de récupération web dans votre requête API :

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: web-fetch-2025-09-10" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "Veuillez analyser le contenu à https://example.com/article"
            }
        ],
        "tools": [{
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5
        }]
    }'

​
Définition de l’outil

L’outil de récupération web prend en charge les paramètres suivants :

JSON
{
  "type": "web_fetch_20250910",
  "name": "web_fetch",

  // Optionnel : Limiter le nombre de récupérations par requête
  "max_uses": 10,

  // Optionnel : Récupérer uniquement depuis ces domaines
  "allowed_domains": ["example.com", "docs.example.com"],

  // Optionnel : Ne jamais récupérer depuis ces domaines
  "blocked_domains": ["private.example.com"],

  // Optionnel : Activer les citations pour le contenu récupéré
  "citations": {
    "enabled": true
  },

  // Optionnel : Longueur maximale du contenu en jetons
  "max_content_tokens": 100000
}

​
Utilisations maximales

Le paramètre max_uses limite le nombre de récupérations web effectuées. Si Claude tente plus de récupérations que autorisé, le web_fetch_tool_result sera une erreur avec le code d’erreur max_uses_exceeded. Il n’y a actuellement aucune limite par défaut.

​
Filtrage de domaine

Lors de l’utilisation de filtres de domaine :

  • Les domaines ne doivent pas inclure le schéma HTTP/HTTPS (utilisez example.com au lieu de https://example.com)
  • Les sous-domaines sont automatiquement inclus (example.com couvre docs.example.com)
  • Les sous-chemins sont pris en charge (example.com/blog)
  • Vous pouvez utiliser soit allowed_domains soit blocked_domains, mais pas les deux dans la même requête.

Soyez conscient que les caractères Unicode dans les noms de domaine peuvent créer des vulnérabilités de sécurité par le biais d’attaques homographiques, où des caractères visuellement similaires de différents scripts peuvent contourner les filtres de domaine. Par exemple, аmazon.com (utilisant le ‘а’ cyrillique) peut apparaître identique à amazon.com mais représente un domaine différent.

Lors de la configuration des listes d’autorisation/blocage de domaines :

  • Utilisez des noms de domaine ASCII uniquement lorsque c’est possible
  • Considérez que les analyseurs d’URL peuvent gérer la normalisation Unicode différemment
  • Testez vos filtres de domaine avec des variations homographiques potentielles
  • Auditez régulièrement vos configurations de domaine pour des caractères Unicode suspects

​
Limites de contenu

Le paramètre max_content_tokens limite la quantité de contenu qui sera incluse dans le contexte. Si le contenu récupéré dépasse cette limite, il sera tronqué. Cela aide à contrôler l’utilisation des jetons lors de la récupération de documents volumineux.

La limite du paramètre max_content_tokens est approximative. Le nombre réel de jetons d’entrée utilisés peut varier d’une petite quantité.

​
Citations

Contrairement à la recherche web où les citations sont toujours activées, les citations sont optionnelles pour la récupération web. Définissez "citations": {"enabled": true} pour permettre à Claude de citer des passages spécifiques des documents récupérés.

Lors de l’affichage des résultats web ou des informations contenues dans les résultats web aux utilisateurs finaux, les citations en ligne doivent être rendues clairement visibles et cliquables dans votre interface utilisateur.

​
Réponse

Voici un exemple de structure de réponse :

{
  "role": "assistant",
  "content": [
    // 1. Décision de Claude de récupérer
    {
      "type": "text",
      "text": "Je vais récupérer le contenu de l'article pour l'analyser."
    },
    // 2. La requête de récupération
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Résultats de récupération
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01234567890abcdef",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Contenu textuel complet de l'article..."
          },
          "title": "Titre de l'Article",
          "citations": {"enabled": true}
        },
        "retrieved_at": "2025-08-25T10:30:00Z"
      }
    },
    // 4. Analyse de Claude avec citations (si activées)
    {
      "text": "Basé sur l'article, ",
      "type": "text"
    },
    {
      "text": "l'argument principal présenté est que l'intelligence artificielle transformera les soins de santé",
      "type": "text",
      "citations": [
        {
          "type": "char_location",
          "document_index": 0,
          "document_title": "Titre de l'Article",
          "start_char_index": 1234,
          "end_char_index": 1456,
          "cited_text": "L'intelligence artificielle est prête à révolutionner la prestation de soins de santé..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

​
Résultats de récupération

Les résultats de récupération incluent :

  • url : L’URL qui a été récupérée
  • content : Un bloc de document contenant le contenu récupéré
  • retrieved_at : Horodatage de quand le contenu a été récupéré

L’outil de récupération web met en cache les résultats pour améliorer les performances et réduire les requêtes redondantes. Cela signifie que le contenu retourné peut ne pas toujours être la dernière version disponible à l’URL. Le comportement du cache est géré automatiquement et peut changer au fil du temps pour optimiser différents types de contenu et modèles d’utilisation.

Pour les documents PDF, le contenu sera retourné sous forme de données encodées en base64 :

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_02",
  "content": {
    "type": "web_fetch_result",
    "url": "https://example.com/paper.pdf",
    "content": {
      "type": "document",
      "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmo..."
      },
      "citations": {"enabled": true}
    },
    "retrieved_at": "2025-08-25T10:30:02Z"
  }
}

​
Erreurs

Lorsque l’outil de récupération web rencontre une erreur, l’API Anthropic retourne une réponse 200 (succès) avec l’erreur représentée dans le corps de la réponse :

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_fetch_tool_error",
    "error_code": "url_not_accessible"
  }
}

Voici les codes d’erreur possibles :

  • invalid_input : Format d’URL invalide
  • url_too_long : L’URL dépasse la longueur maximale (250 caractères)
  • url_not_allowed : URL bloquée par les règles de filtrage de domaine et les restrictions du modèle
  • url_not_accessible : Échec de récupération du contenu (erreur HTTP)
  • too_many_requests : Limite de taux dépassée
  • unsupported_content_type : Type de contenu non pris en charge (seulement texte et PDF)
  • max_uses_exceeded : Utilisations maximales de l’outil de récupération web dépassées
  • unavailable : Une erreur interne s’est produite

​
Validation d’URL

Pour des raisons de sécurité, l’outil de récupération web ne peut récupérer que les URL qui sont apparues précédemment dans le contexte de conversation. Cela inclut :

  • Les URL dans les messages utilisateur
  • Les URL dans les résultats d’outils côté client
  • Les URL des résultats de recherche web ou de récupération web précédents

L’outil ne peut pas récupérer des URL arbitraires que Claude génère ou des URL d’outils serveur basés sur conteneur (Exécution de Code, Bash, etc.).

​
Recherche et récupération combinées

La récupération web fonctionne de manière transparente avec la recherche web pour une collecte d’informations complète :

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Trouvez des articles récents sur l'informatique quantique et analysez le plus pertinent en détail"
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 3
        },
        {
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5,
            "citations": {"enabled": True}
        }
    ],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

Dans ce flux de travail, Claude va :

  1. Utiliser la recherche web pour trouver des articles pertinents
  2. Sélectionner les résultats les plus prometteurs
  3. Utiliser la récupération web pour récupérer le contenu complet
  4. Fournir une analyse détaillée avec citations

​
Mise en cache d’invite

La récupération web fonctionne avec la mise en cache d’invite. Pour activer la mise en cache d’invite, ajoutez des points d’arrêt cache_control dans votre requête. Les résultats de récupération mis en cache peuvent être réutilisés à travers les tours de conversation.

import anthropic

client = anthropic.Anthropic()

# Première requête avec récupération web
messages = [
    {
        "role": "user",
        "content": "Analysez ce document de recherche : https://arxiv.org/abs/2024.12345"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_fetch_20250910",
        "name": "web_fetch"
    }],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

# Ajouter la réponse de Claude à la conversation
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Deuxième requête avec point d'arrêt de cache
messages.append({
    "role": "user",
    "content": "Quelle méthodologie le document utilise-t-il ?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_fetch_20250910",
        "name": "web_fetch"
    }],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

# La deuxième réponse bénéficie des résultats de récupération mis en cache
print(f"Jetons de lecture de cache : {response2.usage.get('cache_read_input_tokens', 0)}")

​
Streaming

Avec le streaming activé, les événements de récupération font partie du flux avec une pause pendant la récupération de contenu :

event: message_start
data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

// Décision de Claude de récupérer

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}}

// URL de récupération streamée
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// Pause pendant l'exécution de la récupération

// Résultats de récupération streamés
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "web_fetch_result", "url": "https://example.com/article", "content": {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "Contenu de l'article..."}}}}}

// La réponse de Claude continue...

​
Requêtes par lots

Vous pouvez inclure l’outil de récupération web dans l’API Messages Batches. Les appels d’outil de récupération web via l’API Messages Batches sont tarifés de la même manière que ceux dans les requêtes API Messages régulières.

​
Utilisation et tarification

Web fetch usage has no additional charges beyond standard token costs:

"usage": {
  "input_tokens": 25039,
  "output_tokens": 931,
  "cache_read_input_tokens": 0,
  "cache_creation_input_tokens": 0,
  "server_tool_use": {
    "web_fetch_requests": 1
  }
}

The web fetch tool is available on the Anthropic API at no additional cost. You only pay standard token costs for the fetched content that becomes part of your conversation context.

To protect against inadvertently fetching large content that would consume excessive tokens, use the max_content_tokens parameter to set appropriate limits based on your use case and budget considerations.

Example token usage for typical content:

  • Average web page (10KB): ~2,500 tokens
  • Large documentation page (100KB): ~25,000 tokens
  • Research paper PDF (500KB): ~125,000 tokens