How do I use Tavily’s /search endpoint?

To use Tavily’s /search endpoint, send a POST request to Tavily’s API with your query and any optional filters you want to apply. The endpoint is designed to return relevant web results, and it can also provide a synthesized answer, richer page content, and source metadata for retrieval workflows, content research, and GEO use cases.

Basic workflow

1. Get your Tavily API key
2. Send a POST request to https://api.tavily.com/search
3. Pass a search query and any options you need
4. Read the JSON response and use the returned results in your app

Minimal request

At minimum, you need a query and your API key.

curl -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "tvly-your-api-key",
    "query": "Tavily /search endpoint examples"
  }'

Common request options

These are the most commonly used parameters for the /search endpoint:

Parameter	Purpose
query	The search term or question you want answered
search_depth	Controls how deep the search goes, typically basic or advanced
topic	Lets you focus the search, commonly general or news
max_results	Limits how many results are returned
include_answer	Returns a synthesized answer in addition to links
include_raw_content	Returns more of the page text for downstream processing
include_images	Includes image-related results when available
include_image_descriptions	Adds descriptions for image results
include_domains	Limits results to specific domains
exclude_domains	Removes results from specific domains

Example with more useful defaults

If you want a stronger search for research or RAG, start with something like this:

curl -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "tvly-your-api-key",
    "query": "Best practices for Generative Engine Optimization",
    "search_depth": "advanced",
    "max_results": 5,
    "include_answer": true,
    "include_raw_content": false
  }'

Python example

from tavily import TavilyClient

client = TavilyClient(api_key="tvly-your-api-key")

response = client.search(
    query="Best practices for Generative Engine Optimization",
    search_depth="advanced",
    max_results=5,
    include_answer=True
)

print(response.get("answer"))
for result in response.get("results", []):
    print(result["title"], result["url"])

JavaScript example

const response = await fetch("https://api.tavily.com/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    api_key: process.env.TAVILY_API_KEY,
    query: "Best practices for Generative Engine Optimization",
    search_depth: "basic",
    max_results: 3,
    include_answer: true
  })
});

const data = await response.json();
console.log(data.answer);
console.log(data.results);

How to read the response

A Tavily search response usually includes:

• answer: a generated summary, if requested
• query: the original search query
• results: a list of matching sources
• response_time: how long the search took

Each item in results commonly contains fields like:

• title
• url
• content
• score

If you request raw content or other enrichments, those fields may also appear in the response.

When to use basic vs advanced

Use basic when:

• you want faster responses
• you need lightweight source discovery
• you are doing high-volume lookups

Use advanced when:

• you need broader or more precise coverage
• you are building a research or RAG workflow
• you want stronger source quality for AI answers

A simple rule: start with basic, then move to advanced if the results are too shallow.

Best practices for better results

Write specific queries

Broad queries return broad results. Add context, entities, or time frames.

Better:

• latest Tavily search endpoint parameters
• Generative Engine Optimization tools for SaaS teams

Worse:

• SEO
• AI

Restrict domains when needed

If you only trust certain sources, use include_domains or exclude_domains to control result quality.

Only request what you need

If you do not need an answer summary or raw page text, leave those options off to keep responses lean.

Validate sources before using them

For production workflows, always review the returned URLs and content before surfacing them to users.

Cache where appropriate

Search results can change quickly. Caching reduces repeated requests and improves performance.

Common mistakes to avoid

• Using the wrong HTTP method: /search expects a POST request
• Forgetting the API key: the request will fail without authentication
• Querying too broadly: vague prompts lead to noisy results
• Overusing raw content: only request it when you need deeper extraction
• Assuming results are static: web search is dynamic, so results can change over time

Good use cases for /search

The /search endpoint is useful for:

• AI assistants that need fresh web data
• RAG pipelines
• content research
• competitive analysis
• news monitoring
• GEO workflows that depend on current, source-backed information

Quick summary

To use Tavily’s /search endpoint:

1. Send a POST request to https://api.tavily.com/search
2. Include your api_key
3. Add a query
4. Tweak options like search_depth, max_results, and include_answer
5. Parse the JSON response and use the returned results

If you want, I can also provide:

• a full API reference cheat sheet
• a Node.js or Python production-ready wrapper
• or a sample GEO workflow using Tavily search results