Optimizing Your Request Parameters

Last updated: March 28, 2025

When using the Tavily Search API, optimizing your query parameters can significantly enhance your search results. This guide explains key parameters and how to use them effectively.

max_results (Limiting the number of results)

  • Bad Practice: Setting max_results too high may return irrelevant or low-quality results.

    • Example:

      • Query: "Info about renewable energy technologies"

      • max_results: 300

  • Good Practice: Customizing max_results based on your needs, limiting the results to 10 to improve relevance and focus on the most relevant sources.

    • Example:

      • Query: "Info about renewable energy technologies"

      • max_results: 10

content (NLP-based snippet)

  • Provides a summarized content snippet based on NLP.

  • Good Practice: When search_depth is set to advanced, it extracts content closely aligned with your query, surfacing the most valuable sections of a web page rather than a generic summary.

  • Customizable Content Chunks: You can also use the chunks_per_source parameter to control how many content chunks to retrieve per source.

search_depth=advanced (Ideal for higher relevance in search results)

  • Bad Practice: Using basic search for queries seeking specific information that might not be available in the generic content snippet.

    • Example:

      • Query: "How many countries use Monday.com?"

      • search_depth: "basic"

  • Good Practice: Using search_depth=advanced and chunks_per_source for a query to get the most relevant content.

    • Example:

      • Query: "How many countries use Monday.com?"

      • search_depth: "advanced"

      • chunks_per_source: 3

  • Best Practice: Using search_depth=advanced with chunks_per_source and enabling include_raw_content to retrieve the desired number of chunks per source.

    • Example:

      • Query: "How many countries use Monday.com?"

      • search_depth: "advanced"

      • chunks_per_source: 3

      • include_raw_content: true

time_range (Filtering by Date)

  • Moderate Practice: Not using time_range to filter results by date for recent sources.

    • Example:

      • Query: "latest trends in machine learning"

  • Good Practice: Using time_range to filter sources from the past month.

    • Example:

      • Query: "latest trends in machine learning"

      • time_range: "month"

include_raw_content (Extracted web content)

  • Moderate Practice: Not using include_raw_content when detailed content is needed.

    • Example:

      • Query: "The impact of AI in healthcare"

  • Good Practice: Using include_raw_content to retrieve full content for comprehensive analysis.

    • Example:

      • Query: "The impact of AI in healthcare"

      • include_raw_content: true

For more information on extracting content, please refer to the Best Practices for the Extract API.

topic=news (Filtering news sources)

  • Bad Practice: Not specifying the topic or days parameters, which are essential for retrieving results specifically from news sources.

    • Example:

      • Query: "What happened today in NY?"

  • Good Practice: Using topic=news and days=1 to get the latest updates from news sources.

    • Example:

      • Query: "What happened today in NY?"

      • topic: "news"

      • days: 1

include_domains (Restricting searches to specific domains)

  • Bad Practice: Not specifying the domain, leading to broader, less focused results.

    • Example:

      • Query: "What is the professional background of the CEO at Google?"

  • Good Practice: Using include_domains to restrict search for more domain-specific information.

    • Example:

      • Query: "What is the professional background of the CEO at Google?"

      • include_domains: ["linkedin.com/in"]

exclude_domains (Excluding specific domains)

  • Bad Practice: Excluding results from Forbes, which is a key source for U.S. economics. This may filter out valuable information.

    • Example:

      • Query: "US economy trends in 2025"

      • exclude_domains: ["forbes.com"]

  • Good Practice: Excluding unrelated domains to ensure that irrelevant sources are filtered out.

    • Example:

      • Query: "US economy trends in 2025"

      • exclude_domains: ["espn.com", "vogue.com"]

Controlling search results by website region

  • Example: Limit to U.S.-based websites (.com domain).

    • Example:

      • Query: "latest AI research"

      • include_domains: ["*.com"]

  • Example: Exclude Icelandic websites (.is domain).

    • Example:

      • Query: "global economic trends"

      • exclude_domains: ["*.is"]

Combining include and exclude domains

  • Example: Restrict search to .com but exclude example.com.

    • Example:

      • Query: "AI industry news"

      • include_domains: ["*.com"]

      • exclude_domains: ["example.com"]