Guide

Tavily, un moteur de recherche qui renvoie du contexte prêt à l'emploi

Tavily est une API de recherche pour agents IA qui renvoie des extraits scorés plutôt que des liens. Endpoints, crédits, tarifs et alternatives.

L'équipe CodeWorlds19 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

Tavily est une API de recherche conçue pour les modèles de langage : elle répond à une requête avec un ensemble d'extraits de contenu portant un score de pertinence numérique, plutôt qu'avec une liste d'adresses que tu devrais récupérer toi-même. Le paquet tavily-python est à la version 0.7.27, @tavily/core à la 0.7.7, tous deux sous licence MIT, et la facturation repose sur des crédits à 0.008 dollar l'unité en paiement à l'usage.

Ce qui revient réellement d'une requête

La différence avec une API de recherche ordinaire tient à une seule chose : qui fait le travail entre trouver une adresse et mettre du texte dans le prompt.

Une API classique renvoie ce que tu vois sur une page de résultats : un titre, une adresse et une courte description que le moteur de recherche a écrite pour un humain sur le point de cliquer sur un lien. Pour qu'un modèle puisse l'utiliser, ton code doit récupérer chaque page, gérer le rendu côté navigateur, retirer la navigation, le pied de page et les bannières de consentement, découper le texte en fragments et décider lesquels comptent pour la question. Cela fait quatre endroits distincts où quelque chose peut casser.

Tavily exécute cette chaîne de son côté et renvoie un résultat déjà traité. Dans le champ results, chaque élément porte title, url, content et score, ce dernier étant un nombre à virgule flottante qui décrit la pertinence par rapport à la requête. Le champ content n'est pas la description de la page de résultats mais un ensemble d'extraits découpés directement dans le corps du texte, où un extrait fait au plus 500 caractères et où leur nombre par source est défini par le paramètre chunks_per_source dans une plage de 1 à 3. Les extraits sont reliés par un séparateur [...], donc le texte montre où l'un se termine et où le suivant commence.

Ce transfert de responsabilité a un prix et il vaut mieux le nommer clairement. Tu paies du contexte prêt à l'emploi plutôt que de la matière brute, donc tu renonces au contrôle de la façon dont le texte est découpé et de ce sur quoi le nombre de pertinence est calculé. L'algorithme de scoring n'est pas décrit dans la documentation, et la valeur de score n'a pas d'échelle de référence définie. Les auteurs eux-mêmes disent seulement, dans le guide des bonnes pratiques, que plus c'est élevé mieux c'est et que le seuil de coupure dépend du cas d'usage. Si tu construis un système où tu dois pouvoir expliquer pourquoi ce paragraphe précis est entré dans la réponse, cette opacité te gênera.

La seconde approche est représentée par Firecrawl, où tu achètes de la matière brute : tu fournis une adresse, tu obtiens le markdown nettoyé de toute la page, et tu décides toi-même du découpage, du scoring et de la sélection. Choisir entre les deux, c'est choisir entre une intégration rapide et le contrôle du processus, pas entre un meilleur et un moins bon outil.

Versions, licence et état des paquets

La licence est ici propre, ce qui après avoir audité d'autres outils de cette collection ressemble à un compliment. J'ai vérifié trois sources et toutes disent la même chose.

Le fichier LICENSE des dépôts tavily-ai/tavily-python et tavily-ai/tavily-js porte le texte de la licence MIT avec une mention de copyright 2024 pour Alpha AI Technologies Inc. Le champ license du registre npm pour @tavily/core indique MIT. Les paquets publiés contiennent bel et bien un fichier de licence : l'archive npm a package/LICENSE, l'archive source PyPI a LICENSE à sa racine, et le wheel d'installation le porte dans tavily_python-0.7.27.dist-info/licenses/LICENSE.

Une petite incohérence existe pourtant. Le champ license dans les métadonnées PyPI de tavily-python est vide, tout comme le champ plus récent license_expression. L'information MIT vit uniquement dans le classifieur License :: OSI Approved :: MIT License. Un outil qui ne récolte les licences que dans le champ license verra donc une valeur vide et marquera le paquet comme non spécifié. Ce n'est pas un problème juridique mais de configuration, et pourtant un rapport de conformité doit pouvoir l'expliquer.

Il faut séparer ici deux choses. Ce qui est ouvert sous MIT, ce sont les clients, quelques milliers de lignes de code qui enveloppent des appels HTTP. Le moteur de recherche lui-même est un service fermé qui tourne sur api.tavily.com sans variante auto-hébergée. L'enfermement chez le fournisseur est réel et total : si Tavily disparaît ou augmente ses prix, il n'y a pas de voie de repli sans réécrire la couche de recherche contre un autre fournisseur.

Les dépendances sont modestes. Le client Python tire requests, httpx et tiktoken en version 0.5.1 ou plus récente. Le client JavaScript tire axios, https-proxy-agent et js-tiktoken. Une bibliothèque de comptage de tokens est présente parce que le SDK peut couper les résultats à un budget de tokens donné avant de les passer au modèle.

Le premier appel et la forme de la réponse

La voie la plus courte pour vérifier si l'outil convient n'a même pas besoin d'un compte. Le mode sans clé s'active avec un en-tête et couvre la recherche et l'extraction de contenu.

Bash
pip install tavily-python
npm i @tavily/core

curl -X POST https://api.tavily.com/search \
  -H "Content-Type: application/json" \
  -H "X-Tavily-Access-Mode: keyless" \
  -d '{"query": "digital accessibility act amendments", "max_results": 3}'

La documentation décrit ce mode comme gratuit et limité en débit, sans indiquer de seuil précis. La réponse est censée avoir un schéma identique à un appel avec clé, donc elle convient pour vérifier la qualité des résultats avant d'ouvrir un compte.

Un vrai appel ressemble à ceci. Chaque nom de paramètre ci-dessous vient de la spécification OpenAPI du endpoint /search.

Python
from tavily import TavilyClient

client = TavilyClient(api_key="tvly-...")

response = client.search(
    query="legal status of the NIS2 directive in Poland",
    search_depth="advanced",
    chunks_per_source=3,
    max_results=5,
    topic="general",
    time_range="month",
    include_domains=["gov.pl", "sejm.gov.pl"],
    include_raw_content=False,
    include_answer=False,
    country="poland",
)

for item in response["results"]:
    print(round(item["score"], 3), item["url"])
    print(item["content"][:200])

Plusieurs choses dans cet appel méritent un commentaire. Le paramètre search_depth accepte quatre valeurs : ultra-fast, fast, basic et advanced, ordonnées de la latence la plus basse à la pertinence la plus haute. La valeur par défaut est basic. La variante ultra-fast se comporte différemment des autres : elle renvoie un résumé par source au lieu d'extraits, donc chunks_per_source n'a plus aucun effet. Le paramètre max_results va de 0 à 20 avec 5 par défaut. La liste include_domains contient jusqu'à 300 entrées, exclude_domains jusqu'à 150. Le paramètre country ne fonctionne que lorsque topic vaut general, donc il n'a aucun effet sur les recherches d'actualités.

La réponse a une forme fixe, et c'est son plus grand atout quand on écrit du code.

JSON
{
  "query": "legal status of the NIS2 directive in Poland",
  "results": [
    {
      "title": "National cybersecurity system",
      "url": "https://www.gov.pl/web/baza-wiedzy/nis2",
      "content": "First snippet [...] second snippet",
      "score": 0.81025416,
      "raw_content": null,
      "id": "a3f9c2-04"
    }
  ],
  "auto_parameters": { "topic": "general", "search_depth": "basic" },
  "response_time": 1.67,
  "usage": { "credits": 1 },
  "request_id": "123e4567-e89b-12d3-a456-426614174111"
}

Les champs query, results, images, response_time et answer sont marqués comme obligatoires dans la spécification. Le champ usage apparaît quand include_usage est défini à true et c'est le seul moyen de connaître le coût d'un appel au moment où il s'exécute, plutôt que d'attendre le panneau de facturation.

Cinq endpoints et la répartition du travail entre eux

La documentation se contredit par endroits, et il vaut mieux le savoir avant de te mettre à chercher quelque chose qui n'existerait soi-disant pas. La section des questions fréquentes liste trois endpoints : Search, Extract et Crawl. La référence de l'API décrit en plus Map, Research, Usage et Logs. La référence correspond à la réalité, la section des questions est simplement périmée.

La répartition des tâches est sensée et correspond directement au coût. Search trouve des pages et en renvoie des extraits. Extract prend des adresses connues et renvoie leur contenu complet. Map parcourt un site comme un graphe et ne renvoie que la liste des adresses, sans récupérer le contenu. Crawl combine Map et Extract, en parcourant le site et en tirant le contenu au passage. Research lance un agent qui cherche, analyse des sources et rédige un rapport avec des citations.

Python
content = client.extract(
    urls=[
        "https://www.gov.pl/web/baza-wiedzy/nis2",
        "https://eur-lex.europa.eu/eli/dir/2022/2555/oj",
    ],
    extract_depth="advanced",
    format="markdown",
    query="obligations of essential entities",
    chunks_per_source=5,
    timeout=30,
    include_usage=True,
)

site_map = client.map(url="https://docs.tavily.com", instructions="pages about the Python SDK")

Pour l'extraction, extract_depth accepte basic ou advanced, la variante avancée allant chercher les tableaux et le contenu intégré au prix de temps de réponse plus longs. Le champ format accepte markdown ou text, markdown par défaut, et la variante texte peut être plus lente. Le paramètre timeout va de 1 à 60 secondes, et sans valeur explicite les valeurs par défaut sont de 10 secondes pour basic et 30 pour advanced. Fournir query active le reranking des extraits par rapport à cette intention, et c'est seulement alors que chunks_per_source s'applique, ici dans une plage de 1 à 5.

Le endpoint Research se comporte différemment des autres car il est asynchrone. Tu crées une tâche, tu reçois un request_id, et tu interroges le statut ou tu écoutes un flux.

Python
task = client.research(
    input="Compare incident reporting requirements in NIS2 and in DORA",
    model="pro",
    citation_format="numeric",
    output_length="long",
    include_domains=["eur-lex.europa.eu"],
    stream=False,
)

print(task["request_id"], task["status"])

Le modèle mini est décrit comme orienté vers des questions étroites et bien délimitées, et pro vers des sujets complexes qui demandent plusieurs angles. Cette différence se traduit en fourchettes de coût, couvertes plus loin. Une limite de débit distincte pour la création de tâches de recherche est de 20 requêtes par minute et est la même pour les clés de développement et de production, tandis que l'interrogation du statut d'une tâche relève de la limite générale.

Crédits, tarifs et limite du plan gratuit

La facturation repose sur des crédits, et la conversion dépend du endpoint que tu utilises et des paramètres. Les crédits se réinitialisent le premier jour de chaque mois, quelle que soit la date de facturation.

OpérationCoût en crédits
Search basic, fast, ultra-fast1 par requête
Search advanced2 par requête
Extract basic1 pour 5 récupérations réussies
Extract advanced2 pour 5 récupérations réussies
Map sans instructions1 pour 10 pages renvoyées
Map avec instructions2 pour 10 pages renvoyées
Crawlcoût du mapping plus coût de l'extraction
Research mini4 à 110 par requête
Research pro15 à 250 par requête

Une récupération de page échouée n'est pas comptée, ni un mapping échoué. Un exemple tiré de la documentation : parcourir dix pages avec extraction basique coûte 1 crédit pour le mapping plus 2 pour l'extraction, soit 3 crédits au total. Les mêmes dix pages avec extraction avancée coûtent 1 plus 4, soit 5 crédits au total.

Les plans mensuels sont les suivants : Researcher donne 1 000 crédits par mois gratuitement, Project 4 000 crédits pour 30 dollars, Bootstrap 15 000 crédits pour 100 dollars, Startup 38 000 crédits pour 220 dollars, Growth 100 000 crédits pour 500 dollars. Le paiement à l'usage coûte 0.008 dollar par crédit. Enterprise est tarifé individuellement.

L'arithmétique est correcte, ce qui après l'expérience d'autres grilles tarifaires vaut la peine d'être vérifié. Diviser le prix par le nombre de crédits donne 0.0075, 0.00667, 0.00579 et 0.005 dollar tour à tour, tandis que la documentation indique 0.0075, 0.0067, 0.0058 et 0.005, les mêmes nombres une fois arrondis. La fourchette déclarée des plans mensuels, de 0.0075 à 0.005 dollar par crédit, tient aussi.

La limite du plan gratuit est une vraie contrainte et doit être convertie dans ton propre cas d'usage. Mille crédits signifient mille recherches basiques ou cinq cents avancées par mois. Un agent qui exécute trois recherches avancées par conversation brûlera cette allocation après moins de 170 conversations. Assez pour un prototype, pas pour la production. Une ligne de la documentation est facile à manquer ici : les clés de production, avec une limite de 1 000 requêtes par minute au lieu de 100, exigent un plan payant actif ou le paiement à l'usage activé. Sur le plan gratuit, tu restes sur la limite de développement.

Une réduction étudiante existe, mais les conditions ne sont pas publiées et l'éligibilité se règle par email avec le support. Le support par email est réservé aux plans payants, et un accord sur la disponibilité et le temps de réponse au seul plan Enterprise.

Fraîcheur des résultats et ce que personne ne garantit

Cette question est généralement posée après qu'une première réponse périmée est arrivée en production, donc mieux vaut l'expliquer avant.

Il n'y a aucune garantie de fraîcheur d'aucune sorte. La documentation décrit les résultats comme à jour et en temps réel, mais n'indique nulle part le retard de l'index, la fenêtre dans laquelle une nouvelle page devient trouvable, ni aucun engagement contractuel à ce sujet. Les seules déclarations contraignantes sur la disponibilité du service concernent le plan Enterprise et parlent de disponibilité et de temps de réponse du support, pas d'actualité des données.

Ce que tu obtiens, ce sont des filtres de dates plutôt qu'une promesse de couverture. Le paramètre time_range accepte day, week, month, year et leurs abréviations d'une lettre. Les paramètres start_date et end_date acceptent des dates au format année-mois-jour. La documentation signale un détail important : le filtrage porte sur la date de publication ou la date de dernière mise à jour de la page. Un site qui actualise sa date de modification à chaque reconstruction passera un filtre time_range réglé sur un jour même si le contenu date de plusieurs années. Le filtre réduit l'ensemble, il ne le vérifie pas.

La conclusion pratique est que les cas d'usage qui dépendent de l'actualité ont besoin d'une couche de contrôle à toi. Règle topic sur news ou finance, car ces catégories sont décrites comme orientées vers l'actualité. Demande au modèle de signaler la date visible dans le texte de l'extrait et compare-la à aujourd'hui de ton côté. Pour les questions sur un état courant où le coût d'une erreur est élevé, aller directement à la source de données vaut mieux qu'aller à un moteur de recherche.

Tavily face aux alternatives

Quatre approches du même problème, ordonnées selon la quantité de travail qui reste de ton côté.

CaractéristiqueTavilyFirecrawlAPI de recherche classiqueRecherche côté fournisseur
Ce qui revientextraits de contenu scoréspage complète en markdowntitre, adresse, courte descriptionréponse du modèle avec références
Qui récupère et nettoie le HTMLle fournisseurle fournisseurton codele fournisseur
Qui découpe le texte en fragmentsle fournisseurton codeton codele fournisseur
Unité de facturationcrédit par appel ou par pagecrédit par pagerequêtetokens plus frais d'outil
Contrôle de la sélection des sourceslistes de domaines, filtres de datescomplet, tu fournis les adresseslistes de domaines, selon le fournisseurlimité
Option d'auto-hébergementaucuneserveur ouvert, licence AGPL-3.0aucuneaucune
Licence du clientMITMITselon le fournisseurlicence du SDK du fournisseur

La règle de choix est courte. Prends Tavily quand un agent doit poser une question au web et recevoir de la matière prête à coller dans un prompt, et que tu préfères ne pas maintenir ta propre récupération de pages. Prends Firecrawl quand les adresses sont connues ou viennent d'un seul site et que tu veux le contenu complet plus le contrôle du découpage. Choisis une API de recherche classique quand tu n'as besoin que d'adresses, pour ton propre index par exemple. La recherche côté fournisseur, disponible dans Claude et dans OpenAI, est le bon choix quand tu veux le moins de pièces mobiles possible plutôt que le contrôle de la sélection des sources.

Une autre approche manque dans cette comparaison. Exa construit son propre index sur des embeddings, donc une requête qui décrit le sens de la page recherchée tombe mieux là que quelques mots-clés. Le prix est double : pour une requête sur un nom propre précis, un numéro de version ou un code d'erreur, la correspondance littérale bat généralement la correspondance sémantique, et l'index et le modèle de classement sont fermés, sans variante que tu puisses exécuter toi-même, donc l'enfermement chez le fournisseur y est complet.

La couche d'intégration est rarement le problème. Tavily fournit des outils pour LangChain et LlamaIndex, un serveur distant qui parle le protocole MCP et une interface en ligne de commande. Pour des tâches qui demandent des clics dans une interface, une connexion ou le remplissage de formulaires, aucun de ces outils ne suffit, et c'est là qu'intervient le pilotage de navigateur du genre browser-use.

Erreurs courantes

La première est de laisser search_depth à sa valeur par défaut et d'être surpris par la qualité des résultats. Le mode basic est un compromis entre temps et pertinence, et les auteurs dans leur guide des agents recommandent carrément advanced, avec chunks_per_source réglé à 3. Cela coûte deux crédits au lieu d'un, donc la différence se voit sur la facture, mais sur des questions de niche elle se voit aussi dans les réponses.

La deuxième est d'activer auto_parameters sans lire les conséquences. Ce drapeau laisse le service choisir lui-même les paramètres, mais la documentation note que search_depth peut être relevé à advanced là où le service juge cela utile. Chaque requête de ce type coûte alors deux crédits au lieu d'un, sans avertissement dans ton code.

La troisième est de traiter time_range comme une garantie de fraîcheur. Le filtre porte sur la date de publication ou de dernière modification, et une bonne part des sites actualisent cette dernière à chaque reconstruction de page. Restreindre au dernier jour ne veut pas dire que le contenu date du dernier jour.

La quatrième est de lancer crawl pour connaître la taille d'un site. Parcourir avec extraction coûte le mapping plus l'extraction, tandis que map seul coûte un crédit pour dix pages et renvoie la liste des adresses. L'ordre correct ne devient évident qu'après la première facture.

La cinquième est de ne pas gérer une réponse 429. La limite pour une clé de développement est de 100 requêtes par minute, pour une clé de production de 1 000, pour le parcours de sites de 100 quel que soit le type de clé, pour la création de tâches de recherche de 20, et pour le endpoint d'usage de 10 par dix minutes. La réponse porte un en-tête retry-after avec un nombre de secondes, et c'est cette valeur qui doit piloter la nouvelle tentative.

La sixième est d'omettre include_usage. Sans ce champ, tu ne connais pas le coût d'un appel au moment où il s'exécute, et pour les tâches de recherche l'écart est énorme, car une seule requête sur le modèle pro tombe n'importe où entre 15 et 250 crédits. C'est la différence entre un et seize pour cent de toute l'allocation mensuelle gratuite.

La septième est de garder la clé côté navigateur. Le client JavaScript s'exécute aussi dans un navigateur, donc la tentation est réelle, et le résultat est le même que pour toute autre clé d'API : la facture tombe sur toi et la clé est visible de quiconque ouvre les outils de développement.

FAQ

En quoi Tavily diffère-t-il d'une API de recherche ordinaire ?

Une API ordinaire renvoie un titre, une adresse et une description de page de résultats, en te laissant la récupération et le nettoyage. Tavily renvoie des extraits découpés dans le corps du texte, de cinq cents caractères au plus chacun, avec une valeur de pertinence numérique dans le champ score. Tu achètes du contexte prêt à l'emploi au lieu de matière brute, en payant avec le contrôle de la façon dont le découpage et le scoring se font.

Jusqu'où va réellement le plan gratuit ?

Mille crédits par mois, c'est-à-dire mille recherches basiques ou cinq cents avancées. Aucune carte n'est requise et les crédits se réinitialisent le premier jour du mois. Une clé de production avec une limite de 1 000 requêtes par minute exige cependant un plan payant ou le paiement à l'usage activé, donc sur le plan gratuit tu restes à 100 requêtes par minute.

Tavily garantit-il la fraîcheur des résultats ?

Non. La documentation décrit les résultats comme actuels mais n'indique aucun retard d'index ni aucun engagement à ce sujet. Ce que tu obtiens, ce sont les filtres time_range, start_date et end_date, qui portent sur la date de publication ou de dernière mise à jour d'une page. L'accord sur la disponibilité et le temps de réponse ne couvre que le plan Enterprise et ne s'étend pas à l'actualité des données.

Tavily peut-il être auto-hébergé ?

Non. Ce qui est ouvert sous MIT, ce sont les clients, tavily-python et @tavily/core, tandis que le moteur de recherche lui-même est un service fermé sur api.tavily.com. L'enfermement chez le fournisseur est total, donc il vaut mieux garder la couche de recherche de ton code derrière une interface à toi, pour que changer de fournisseur ne signifie pas réécrire l'application.

Quand choisir Firecrawl plutôt que Tavily ?

Quand tu connais les adresses ou que tu travailles au sein d'un seul site et que tu as besoin du contenu complet de la page plutôt que d'extraits choisis. Firecrawl propose aussi un serveur auto-hébergé sous licence AGPL-3.0, ce que Tavily n'offre pas. Dans l'autre sens : quand le point de départ est une question plutôt qu'une adresse, Tavily t'épargne toute l'étape de récupération et de découpage.

Ai-je besoin d'un compte pour essayer ?

Non. Le mode sans clé couvre la recherche et l'extraction de contenu, s'active avec l'en-tête X-Tavily-Access-Mode: keyless et renvoie des réponses au schéma identique à celui des appels avec clé. La documentation le décrit comme gratuit et limité en débit sans indiquer de seuil, donc il convient pour juger la qualité des résultats plutôt que pour un travail de production.

La spécification complète des paramètres se trouve dans la référence de l'API, la conversion des crédits dans la section tarifs, et le code des clients dans les dépôts tavily-python et tavily-js.

À lire aussi