JavaScript
Integrate Tavily’s powerful APIs natively in your JavaScript/TypeScript projects.
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.
Tavily Search
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
Parameter | Type | Description | Default |
---|---|---|---|
query (required) | string | The query to run a search on. | |
searchDepth | string | The depth of the search. It can be "basic" or "advanced" . | "basic" |
topic | string | The category of the search. Determines which agent will be used. Supported values are "general" and "news" . | "general" |
days | number | The number of days back from the current date to include in the results. Available only when using the "news" topic. | 3 |
timeRange | string | The time range back from the current date. Accepted values include "day" , "week" , "month" , "year" or shorthand values "d" , "w" , "m" , "y" . | |
maxResults | number | The maximum number of search results to return. It must be between 0 and 20 . | 5 |
includeImages | boolean | Include a list of query-related images in the response. | false |
includeImageDescriptions | boolean | Include a list of query-related images and their descriptions in the response. | false |
includeAnswer | boolean or string | Include 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 |
includeRawContent | boolean | Include the cleaned and parsed HTML content of each search result. | false |
includeDomains | Array<string> | A list of domains to specifically include in the search results. | [] |
excludeDomains | Array<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:
Key | Type | Description |
---|---|---|
results | Array<Result> | A list of sorted search results ranked by relevancy. |
query | string | Your search query. |
responseTime | number | Your search result response time. |
answer (optional) | string | The 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:
Key | Type | Description |
---|---|---|
title | string | The title of the search result. |
url | string | The URL of the search result. |
content | string | The most query-related content from the scraped URL. Tavily uses proprietary AI to extract the most relevant content based on context quality and size. |
score | float | The relevance score of the search result. |
rawContent (optional) | string | The parsed and cleaned HTML content of the site. This is only available if includeRawContent is set to true . |
publishedDate (optional) | string | The 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:
Key | Type | Description |
---|---|---|
url | str | The URL of the image. |
description (optional) | str | This 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
Parameter | Type | Description | Default |
---|---|---|---|
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. | |
includeImages | boolean | Include a list of images extracted from the URLs in the response. | false |
extractDepth | string | The 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:
Key | Type | Description |
---|---|---|
results | Array<SuccessfulResult> | A list of extracted content. |
failed_results | Array<FailedResult> | A list of URLs that could not be processed. |
response_time | number | The search result response time. |
Successful Results
Each successful result in the results
list will be in the following SuccessfulResult
format:
Key | Type | Description |
---|---|---|
url | string | The URL of the webpage. |
raw_content | string | The 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:
Key | Type | Description |
---|---|---|
url | string | The URL that failed. |
error | string | An error message describing why it could not be processed. |