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" })

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"."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.3
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
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
includeDomainsArray<string>A list of domains to specifically include in the search results.[]
excludeDomainsArray<string>A list of domains to specifically exclude from the search results.[]

Response format

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

KeyTypeDescription
resultsArray<Result>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)Array<string> or Array<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
urlstrThe URL of the image.
description (optional)strThis 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 or Array<string>The URL (or URLs) you want to extract. If a list is provided, it 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"

Response format

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

KeyTypeDescription
resultsArray<SuccessfulResult>A list of extracted content.
failed_resultsArray<FailedResult>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)Array<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