Instantiating a client

To interact with Tavily in JavaScript, you must instatiate a client with your API key. Our client is asynchronous by default.

Once you have instantiated a client, call one of our supported methods (detailed below) to access the API.

const { tavily } = require("@tavily/core");

client = tavily({ apiKey: "tvly-YOUR_API_KEY" });

Proxies

If you would like to specify a proxy to be used when making requests, you can do so by passing in a proxy parameter on client instantiation.

Proxy configuration is available in both the synchronous and asynchronous clients.

const { tavily } = require("@tavily/core");

const proxies = {
  http: "<your HTTP proxy>",
  https: "<your HTTPS proxy>",
};

client = tavily({ apiKey: "tvly-YOUR_API_KEY", proxies });

Alternatively, you can specify which proxies to use by setting the TAVILY_HTTP_PROXY and TAVILY_HTTPS_PROXY variables in your environment file.

NEW! Try our interactive API Playground to see each parameter in action, and generate ready-to-use JavaScript snippets.

You can access Tavily Search in JavaScript through the client’s search function.

Parameters

ParameterTypeDescriptionDefault
query (required)stringThe query to run a search on.
searchDepthstringThe depth of the search. It can be "basic" or "advanced". "advanced" search is tailored to retrieve the most relevant sources and content snippets for your query, while "basic" search provides generic content snippets from each source."basic"
topicstringThe category of the search. Determines which agent will be used. Supported values are "general" and "news"."general"
daysnumberThe number of days back from the current date to include in the results. Available only when using the "news" topic.7
timeRangestringThe time range back from the current date. Accepted values include "day", "week", "month", "year" or shorthand values "d", "w", "m", "y".
maxResultsnumberThe maximum number of search results to return. It must be between 0 and 20.5
chunksPerSourcenumberThe number of content chunks to retrieve from each source. Each chunk’s length is maximum 500 characters. It must be between 1 and 3. Available only when searchDepth is "advanced".
includeImagesbooleanInclude a list of query-related images in the response.false
includeImageDescriptionsbooleanInclude a list of query-related images and their descriptions in the response.false
includeAnswerboolean or stringInclude an answer to the query generated by an LLM based on search results. A "basic" (or true) answer is quick but less detailed; an "advanced" answer is more detailed.false
includeRawContentbooleanInclude the cleaned and parsed HTML content of each search result.false
includeDomainsstring[]A list of domains to specifically include in the search results.[]
excludeDomainsstring[]A list of domains to specifically exclude from the search results.[]
timeoutnumberA timeout to be used in requests to the Tavily API.60

Response format

The response object you receive will be in the following format:

KeyTypeDescription
resultsResult[]A list of sorted search results ranked by relevancy.
querystringYour search query.
responseTimenumberYour search result response time.
answer (optional)stringThe answer to your search query, generated by an LLM based on Tavily’s search results. This is only available if includeAnswer is set to true.
images (optional)string[] or ImageResult[]This is only available if includeImages is set to true. A list of query-related image URLs. If includeImageDescriptions is set to true, each entry will be an ImageResult.

Results

Each result in the results list will be in the following Result format:

KeyTypeDescription
titlestringThe title of the search result.
urlstringThe URL of the search result.
contentstringThe most query-related content from the scraped URL. Tavily uses proprietary AI to extract the most relevant content based on context quality and size.
scorefloatThe relevance score of the search result.
rawContent (optional)stringThe parsed and cleaned HTML content of the site. This is only available if includeRawContent is set to true.
publishedDate (optional)stringThe publication date of the source. This is only available if the search topic is set to news.

Image Results

Each image in the images list will be in the following ImageResult format:

KeyTypeDescription
urlstringThe URL of the image.
description (optional)stringThis is only available if includeImageDescriptions is set to true. An LLM-generated description of the image.

Example

Tavily Extract

You can access Tavily Extract in JavaScript through the client’s extract function.

Parameters

ParameterTypeDescriptionDefault
urls (required)string[]The URLs you want to extract. The list must not contain more than 20 URLs.
includeImagesbooleanInclude a list of images extracted from the URLs in the response.false
extractDepthstringThe depth of the extraction process. You may experience higher latency with "advanced" extraction, but it offers a higher success rate and retrieves more data from the URL (e.g., tables, embedded content). "basic" extraction costs 1 API Credit per 5 successful URL extractions, while "advanced" extraction costs 2 API Credits per 5 successful URL extractions."basic"
timeoutnumberA timeout to be used in requests to the Tavily API.60

Response format

The response object you receive will be in the following format:

KeyTypeDescription
resultsSuccessfulResult[]A list of extracted content.
failed_resultsFailedResult[]A list of URLs that could not be processed.
response_timenumberThe search result response time.

Successful Results

Each successful result in the results list will be in the following SuccessfulResult format:

KeyTypeDescription
urlstringThe URL of the webpage.
raw_contentstringThe raw content extracted.
images (optional)string[]This is only available if includeImages is set to true. A list of extracted image URLs.

Failed Results

Each failed result in the results list will be in the following FailedResult format:

KeyTypeDescription
urlstringThe URL that failed.
errorstringAn error message describing why it could not be processed.

Example

Tavily Crawl

Our agent-first crawl endpoint, Tavily Crawl is currently in invite-only beta. If you are interested in joining the beta, please email support@tavily.com.

You can access Tavily Crawl in JavaScript through the client’s crawl function.

Parameters

ParameterTypeDescriptionDefault
url (required)stringThe root URL to begin the crawl.
maxDepthnumberMax depth of the crawl. Defines how far from the base URL the crawler can explore.1
maxBreadthnumberMax number of links to follow per level of the tree (i.e., per page).20
limitnumberTotal number of links the crawler will process before stopping.50
instructionsstringNatural language instructions for the crawler.
selectPathsstring[]Regex patterns to select only URLs with specific path patterns (e.g., "/docs/.*", "/api/v1.*").[]
selectDomainsstring[]Regex patterns to select crawling to specific domains or subdomains (e.g., "^docs\.example\.com$").[]
excludePathsstring[]Regex patterns to exclude URLs with specific path patterns (e.g., "/admin/.*", "/private/.*").[]
excludeDomainsstring[]Regex patterns to exclude specific domains or subdomains from crawling (e.g., "^admin\.example\.com$").[]
allowExternalbooleanWhether to return links from external domains in crawl output.false
includeImagesbooleanWhether to extract image URLs from the crawled pages.false
categoriesstring[]Filter URLs using predefined categories. Options: "Careers", "Blog", "Documentation", "About", "Pricing", "Community", "Developers", "Contact", "Media"[]
extractDepthstringAdvanced extraction retrieves more data, including tables and embedded content, with higher success but may increase latency. Options: "basic" or "advanced"."basic"
timeoutnumberA timeout to be used in requests to the Tavily API.60

Response format

The response object you receive will be in the following format:

KeyTypeDescription
baseUrlstringThe URL you started the crawl from.
resultsResult[]A list of crawled pages.
responseTimenumberThe crawl response time.

Results

Each successful result in the results list will be in the following Result format:

KeyTypeDescription
urlstringThe URL of the webpage.
rawContentstringThe raw content extracted.
imagesstring[]Image URLs extracted from the page.

Example

Tavily Map

Our agent-first mapping endpoint, Tavily Map is currently in invite-only beta. If you are interested in joining the beta, please email support@tavily.com.

You can access Tavily Map in JavaScript through the client’s map function.

Parameters

ParameterTypeDescriptionDefault
url (required)stringThe root URL to begin the mapping.
maxDepthnumberMax depth of the mapping. Defines how far from the base URL the crawler can explore.1
maxBreadthnumberMax number of links to follow per level of the tree (i.e., per page).20
limitnumberTotal number of links the crawler will process before stopping.50
instructionsstringNatural language instructions for the mapper.
selectPathsstring[]Regex patterns to select only URLs with specific path patterns (e.g., "/docs/.*", "/api/v1.*").[]
selectDomainsstring[]Regex patterns to select crawling to specific domains or subdomains (e.g., "^docs\.example\.com$").[]
excludePathsstring[]Regex patterns to exclude URLs with specific path patterns (e.g., "/admin/.*", "/private/.*").[]
excludeDomainsstring[]Regex patterns to exclude specific domains or subdomains from mapping (e.g., "^admin\.example\.com$").[]
allowExternalbooleanWhether to return links from external domains in crawl output.false
categoriesstring[]Filter URLs using predefined categories. Options: "Careers", "Blog", "Documentation", "About", "Pricing", "Community", "Developers", "Contact", "Media"[]
timeoutnumberA timeout to be used in requests to the Tavily API.60

Response format

The response object you receive will be in the following format:

KeyTypeDescription
baseUrlstringThe URL you started the crawl from.
resultsstring[]A list of URLs that were discovered during the mapping.
responseTimenumberThe crawl response time.

Example