Skip to main content

Tavily query tutorial

Learn how to search the web with Tavily in Retool.

After setting up a Tavily integration with Retool, your Tavily resource is available to use in the query editor.

Create a query​

Switch to the new app builder

Retool recommends using the new app builder so you can use natural language to build React-based apps using AI.

To create a Tavily query in a Retool app:

  1. In the Retool app IDE, open the Code tab, then click + in the page or global scope.
  2. Select Resource query.
  3. Choose your Tavily resource.
  4. Configure the search query and options.

Query configuration fields​

A Tavily query performs a single web search operation, configured with the following fields. For a full reference of the underlying Tavily Search API, refer to the Tavily API documentation.

Search query​

The search query to send to Tavily. Supports embedded expressions to build the query dynamically from component values.

Example
Latest news on renewable energy
Example with embedded expressions
{{ searchInput.value }}

Topic​

The category of the search.

  • General: Broader searches that include a wide range of sources.
  • News: Real-time updates, particularly about politics, sports, and major current events.

Defaults to General.

Max messages​

The maximum number of search results to return. Accepts a static number or an embedded expression that evaluates to a number.

Examples
5
Dynamic from a component
{{ resultsCountInput.value }}

Defaults to 5.

Domains to include​

Restrict the search to specific domains. Provide a JSON array of domains, without protocol or path.

Example
["example.com", "docs.example.org"]

Leave empty to search all domains.

Domains to exclude​

Exclude specific domains from the search results. Provide a JSON array of domains, without protocol or path.

Example
["example.com", "docs.example.org"]

Leave empty to apply no exclusions.

Common use cases​

search the web and display results

First, create a query named webSearchQuery with a search query built from user input.

Example search query
{{ searchInput.value }}

Next, add a Table component to the app and set its Data property to {{ webSearchQuery.data.results }} to display the returned titles, URLs, and content.

restrict search results to trusted domains

First, create a query and set Domains to Include to a JSON array of the domains you trust for this use case.

Example
["nytimes.com", "reuters.com", "apnews.com"]

Next, set the Search query field with the topic set to News to retrieve recent articles only from those sources.

summarize search results with an agent tool

First, add a Tavily resource query as a tool available to an agent.

Next, describe when the agent should use the tool, such as "search the web for current information the user asks about."

The agent passes the user's question as the Search query and can use the returned answer and results fields to compose a response.

exclude specific domains from a search

First, create a query and set Domains to Exclude to a JSON array of domains you want to filter out.

Example
["pinterest.com", "quora.com"]

Next, run the query and display {{ query1.data.results }} in a Table component to review the filtered results.

Best practices​

Follow these best practices to keep Tavily queries fast, efficient, and safe.

Performance​

  • Limit result count: Set Max messages to only as many results as your app or agent tool actually uses to reduce response size and improve response times.
  • Cache stable searches: For queries that don't need real-time results, enable query caching to reduce API calls.
  • Narrow with domains: Use Domains to Include to reduce the scope of a search instead of filtering a larger result set client-side.
  • Set appropriate timeouts: Configure query timeouts based on expected response times to prevent hung requests.

Data integrity​

  • Validate user input: Sanitize and validate user-provided search queries before including them in a query to prevent unexpected input from reaching the API.
  • Handle errors gracefully: Configure error notifications and fallback behavior for failed queries, including rate limit errors.
  • Verify responses: Check that results and answer are present in the response before using them in your app or agent tool.
  • Implement retry logic: For transient failures, use Retool's automatic retry settings or implement custom retry logic with exponential backoff.
  • Log query activity: Enable query logging to track search requests and responses for debugging and auditing.

Troubleshoot rate limit errors​

If a query fails with a message about exceeding the Tavily web search limit, your organization has hit the rate limit on Retool's managed API key.

  • Wait and retry: The per-minute limit resets after a minute, and the daily limit resets after 24 hours.
  • Bring your own key: Enable Provide my own API key on the resource and provide a Tavily API key to avoid Retool's managed rate limits.