Tavily Integration¶

Tavily provides a search API for AI agents. Use KeyPool to call Tavily with your team token and a stable base URL.

KeyPool Endpoint for Tavily¶

For clients that cannot preserve a service path prefix, send requests to your KeyPool base URL with the x-keypool-service header:

{YOUR_KEYPOOL_BASE_URL}

Use the x-keypool-service: tavily header with this base URL.

Authentication¶

Use your KeyPool team token as a bearer token when making requests to the KeyPool Tavily endpoint.

Do not send a personal Tavily API key when using KeyPool.

Key Features and Usage¶

KeyPool supports Tavily's official endpoints: /search, /extract, /crawl, /map, /research, /research/{request_id}, and /usage. The examples below demonstrate raw HTTP requests. SDKs can also use KeyPool with the x-keypool-service header when they cannot preserve a service path prefix.

1. Basic Search¶

Perform a web search using natural language queries.

Python Example (using requests):

import os
import requests
import json

KEYPOOL_BASE_URL = os.environ.get("KEYPOOL_BASE_URL")
KEYPOOL_TOKEN = os.environ.get("KEYPOOL_TOKEN")

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {KEYPOOL_TOKEN}",
    "x-keypool-service": "tavily",
}

payload = {
    "query": "latest advancements in AI large language models",
    "search_depth": "basic",
    "include_answer": False,
    "include_raw_content": False,
    "max_results": 5,
}

response = requests.post(f"{KEYPOOL_BASE_URL}/search", headers=headers, data=json.dumps(payload))
response.raise_for_status() # Raise an exception for HTTP errors

search_results = response.json()
print("Search Results:")
for result in search_results["results"]:
    print(f"- {result['title']} ({result['url']})")

TypeScript Example (using fetch):

const KEYPOOL_BASE_URL = process.env.KEYPOOL_BASE_URL;
const KEYPOOL_TOKEN = process.env.KEYPOOL_TOKEN;

async function tavilyBasicSearch() {
  const headers = {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${KEYPOOL_TOKEN}`,
    "x-keypool-service": "tavily",
  };

  const payload = {
    query: "latest advancements in AI large language models",
    search_depth: "basic",
    include_answer: false,
    include_raw_content: false,
    max_results: 5,
  };

  const response = await fetch(`${KEYPOOL_BASE_URL}/search`, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const searchResults = await response.json();
  console.log("Search Results:");
  searchResults.results.forEach((result: any) => {
    console.log(`- ${result.title} (${result.url})`);
  });
}

tavilyBasicSearch();

Error Handling¶

KeyPool handles various error conditions gracefully, providing informative responses. Common error scenarios include:

401 Unauthorized: Invalid or missing KeyPool Team Token.
403 Forbidden: Your Team Token does not have permission to access the Tavily service.
429 Quota Exceeded: Your team's rate limit for Tavily has been reached.
503 No Available Keys: Tavily is temporarily unavailable through your KeyPool workspace.
502 Upstream Failed: The request to the Tavily API failed (e.g., network error, Tavily API down).

Interactive API Reference¶

For all Tavily endpoints and in-browser testing, see API Reference → Tavily.