# Tavily Search - Documentation

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown is available with `Accept: text/markdown` and `.md` URL variants.

Source: /docs/api-reference/model-apis-tavily-search

# Tavily Search

POST

/

v3

/

tavily

/

search

Try it

Tavily Search

cURL

```
curl --request POST \
--url https://api.novita.ai/v3/tavily/search \
--header 'Authorization: ' \
--header 'Content-Type: ' \
--data '
{
"query": "",
"search_depth": [
""
],
"chunks_per_source": 123,
"max_results": 123,
"topic": [
""
],
"time_range": [
""
],
"start_date": "",
"end_date": "",
"include_answer": [
{}
],
"include_raw_content": [
{}
],
"include_images": {},
"include_images_descriptions": {},
"include_favicon": {},
"include_domains": {},
"exclude_domains": {},
"country": [
""
],
"auto_parameters": true,
"exact_match": true
}
'
```

```
import requests

url = "https://api.novita.ai/v3/tavily/search"

payload = {
"query": "",
"search_depth": [""],
"chunks_per_source": 123,
"max_results": 123,
"topic": [""],
"time_range": [""],
"start_date": "",
"end_date": "",
"include_answer": [{}],
"include_raw_content": [{}],
"include_images": {},
"include_images_descriptions": {},
"include_favicon": {},
"include_domains": {},
"exclude_domains": {},
"country": [""],
"auto_parameters": True,
"exact_match": True
}
headers = {
"Content-Type": "",
"Authorization": ""
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

```
const options = {
method: 'POST',
headers: {'Content-Type': '', Authorization: ''},
body: JSON.stringify({
query: '',
search_depth: [''],
chunks_per_source: 123,
max_results: 123,
topic: [''],
time_range: [''],
start_date: '',
end_date: '',
include_answer: [{}],
include_raw_content: [{}],
include_images: {},
include_images_descriptions: {},
include_favicon: {},
include_domains: {},
exclude_domains: {},
country: [''],
auto_parameters: true,
exact_match: true
})
};

fetch('https://api.novita.ai/v3/tavily/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
```

```
"https://api.novita.ai/v3/tavily/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => '',
'search_depth' => [
''
],
'chunks_per_source' => 123,
'max_results' => 123,
'topic' => [
''
],
'time_range' => [
''
],
'start_date' => '',
'end_date' => '',
'include_answer' => [
[

]
],
'include_raw_content' => [
[

]
],
'include_images' => [

],
'include_images_descriptions' => [

],
'include_favicon' => [

],
'include_domains' => [

],
'exclude_domains' => [

],
'country' => [
''
],
'auto_parameters' => true,
'exact_match' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: ",
"Content-Type: "
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
```

```
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://api.novita.ai/v3/tavily/search"

payload := strings.NewReader("{\n \"query\": \"\",\n \"search_depth\": [\n \"\"\n ],\n \"chunks_per_source\": 123,\n \"max_results\": 123,\n \"topic\": [\n \"\"\n ],\n \"time_range\": [\n \"\"\n ],\n \"start_date\": \"\",\n \"end_date\": \"\",\n \"include_answer\": [\n {}\n ],\n \"include_raw_content\": [\n {}\n ],\n \"include_images\": {},\n \"include_images_descriptions\": {},\n \"include_favicon\": {},\n \"include_domains\": {},\n \"exclude_domains\": {},\n \"country\": [\n \"\"\n ],\n \"auto_parameters\": true,\n \"exact_match\": true\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Content-Type", "")
req.Header.Add("Authorization", "")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
```

```
HttpResponse response = Unirest.post("https://api.novita.ai/v3/tavily/search")
.header("Content-Type", "")
.header("Authorization", "")
.body("{\n \"query\": \"\",\n \"search_depth\": [\n \"\"\n ],\n \"chunks_per_source\": 123,\n \"max_results\": 123,\n \"topic\": [\n \"\"\n ],\n \"time_range\": [\n \"\"\n ],\n \"start_date\": \"\",\n \"end_date\": \"\",\n \"include_answer\": [\n {}\n ],\n \"include_raw_content\": [\n {}\n ],\n \"include_images\": {},\n \"include_images_descriptions\": {},\n \"include_favicon\": {},\n \"include_domains\": {},\n \"exclude_domains\": {},\n \"country\": [\n \"\"\n ],\n \"auto_parameters\": true,\n \"exact_match\": true\n}")
.asString();
```

```
require 'uri'
require 'net/http'

url = URI("https://api.novita.ai/v3/tavily/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = ''
request["Authorization"] = ''
request.body = "{\n \"query\": \"\",\n \"search_depth\": [\n \"\"\n ],\n \"chunks_per_source\": 123,\n \"max_results\": 123,\n \"topic\": [\n \"\"\n ],\n \"time_range\": [\n \"\"\n ],\n \"start_date\": \"\",\n \"end_date\": \"\",\n \"include_answer\": [\n {}\n ],\n \"include_raw_content\": [\n {}\n ],\n \"include_images\": {},\n \"include_images_descriptions\": {},\n \"include_favicon\": {},\n \"include_domains\": {},\n \"exclude_domains\": {},\n \"country\": [\n \"\"\n ],\n \"auto_parameters\": true,\n \"exact_match\": true\n}"

response = http.request(request)
puts response.read_body
```

200

```
{
"400": {},
"401": {},
"403": {},
"404": {},
"429": {},
"500": {},
"502": {},
"503": {},
"query": "",
"answer": "",
"images": [
{}
],
"results": [
{}
],
"response_time": 123,
"auto_parameters": {},
"request_id": "",
"url": "",
"description": "",
"title": "",
"content": "",
"score": 123,
"raw_content": "",
"favicon": ""
}
```

Tavily is a web data retrieval API designed for developers and AI applications. This document describes the Tavily passthrough endpoints exposed by the platform gateway. It is based on Tavily’s Search API with platform route prefixes applied.
Base URL example: `https://api.novita.ai`
Search the internet by keyword or natural-language question and retrieve a list of matching results (title, URL, summary/snippet, etc.).

##

[​](#request-headers)

Request Headers

All endpoints require platform API authentication.

[​](#param-content-type)

Content-Type

string

required

Use `application/json`.

[​](#param-authorization)

Authorization

string

required

Platform API key, formatted as `Bearer <api_key>`.

##

[​](#request-body)

Request Body

[​](#param-query)

query

string

required

Search query. Minimum length is 1.

[​](#param-search-depth)

search_depth

string[]

Search mode. Common values include `advanced`, `basic`, `fast`, `ultra-fast`. `basic` is set as the default value.

[​](#param-chunks-per-source)

chunks_per_source

integer

Max number of content snippets per source to return. Default is `3`; range is `1` to `3`. Available only when `search_depth` is `advanced`.

[​](#param-max-results)

max_results

integer

Max number of results to return. Default is `5`; supported public range is `1` to `20`.

[​](#param-topic)

topic

string[]

Data category hint. Known values include `news`, `general`, and `finance`.

[​](#param-time-range)

time_range

string[]

Include links published or updated from the time range to now. Common values include `day`,`d`, `week`, `w`, `month`, `m`, `year`, and `y`.

[​](#param-start-date)

start_date

string

Include links published after this YYYY-MM-DD date-time.

[​](#param-end-date)

end_date

string

Include links published before this YYYY-MM-DD date-time.

[​](#param-include-answer)

include_answer

boolean | string[]

Returns an LLM-generated answer. `basic` and `true` returns quick answers; `advanced` returns detailed answers.

[​](#param-include-raw-content)

include_raw_content

boolean | string[]

Returns result in HTML content. `markdown` or `true` returns in markdown; `text` returns in plain text.

[​](#param-include-images)

include_images

boolean

Returns a list of images along with the response.

[​](#param-include-images-descriptions)

include_images_descriptions

boolean

Includes a description to each image. Only works when `include_images` is `true`.

[​](#param-include-favicon)

include_favicon

boolean

Include favicon URL from result.

[​](#param-include-domains)

include_domains

string[]

Restrict results to these domains. Maximum 300 domains.

[​](#param-exclude-domains)

exclude_domains

string[]

Exclude results from these domains. Maximum 150 domains.

[​](#param-country)

country

string[]

Prioritize results from specified country. Only works when topic is `general`. Known values include `afghanistan`, `albania`, `algeria`, `andorra`, `angola`, `argentina`, `armenia`, `australia`, `austria`, `azerbaijan`, `bahamas`, `bahrain`, `bangladesh`, `barbados`, `belarus`, `belgium`, `belize`, `benin`, `bhutan`, `bolivia`, `bosnia and herzegovina`, `botswana`, `brazil`, `brunei`, `bulgaria`, `burkina faso`, `burundi`, `cambodia`, `cameroon`, `canada`, `cape verde`, `central african republic`, `chad`, `chile`, `china`, `colombia`, `comoros`, `congo`, `costa rica`, `croatia`, `cuba`, `cyprus`, `czech republic`, `denmark`, `djibouti`, `dominican republic`, `ecuador`, `egypt`, `el salvador`, `equatorial guinea`, `eritrea`, `estonia`, `ethiopia`, `fiji`, `finland`, `france`, `gabon`, `gambia`, `georgia`, `germany`, `ghana`, `greece`, `guatemala`, `guinea`, `haiti`, `honduras`, `hungary`, `iceland`, `india`, `indonesia`, `iran`, `iraq`, `ireland`, `israel`, `italy`, `jamaica`, `japan`, `jordan`, `kazakhstan`, `kenya`, `kuwait`, `kyrgyzstan`, `latvia`, `lebanon`, `lesotho`, `liberia`, `libya`, `liechtenstein`, `lithuania`, `luxembourg`, `madagascar`, `malawi`, `malaysia`, `maldives`, `mali`, `malta`, `mauritania`, `mauritius`, `mexico`, `moldova`, `monaco`, `mongolia`, `montenegro`, `morocco`, `mozambique`, `myanmar`, `namibia`, `nepal`, `netherlands`, `new zealand`, `nicaragua`, `niger`, `nigeria`, `north korea`, `north macedonia`, `norway`, `oman`, `pakistan`, `panama`, `papua new guinea`, `paraguay`, `peru`, `philippines`, `poland`, `portugal`, `qatar`, `romania`, `russia`, `rwanda`, `saudi arabia`, `senegal`, `serbia`, `singapore`, `south africa`, `south korea`, `south sudan`, `spain`, `sri lanka`, `sudan`, `sweden`, `slovakia`, `slovenia`, `somalia`, `south africa`, `south korea`, `south sudan`, `spain`, `sri lanka`, `sudan`, `sweden`, `switzerland`, `syria`, `taiwan`, `tajikista`, `tanzania`, `thailand`, `togo`, `trinidad and tobago`, `tunisia`, `turkey`, `turkmenistan`, `uganda`, `ukraine`, `united arab emirates`, `united kingdom`, `united states`, `uruguay`, `uzbekistan`, `venezuela`, `vietnam`, `yemen`, `zambia`, and `zimbabwe`.

[​](#param-auto-parameters)

auto_parameters

boolean

Automatically sets parameters for search. `include_answer`, `include_raw_content`,and `max_results` must be set manually if needed. `search_depth` may be set to `advanced` if `search_depth` is not explicitly set.

[​](#param-exact-match)

exact_match

boolean

Returns results containing the exact quoted phrase(s) from the query. Punctuation is ignored.

##

[​](#request-example)

Request Example

```
curl -s -X POST 'https://api.novita.ai/v3/tavily/search' \
-H 'Authorization: Bearer sk-123' \
-H 'Content-Type: application/json' \
-d '{
"query": "Who is Leo Messi?",
"auto_parameters": false,
"topic": "general",
"search_depth": "basic",
"chunks_per_source": 3,
"max_results": 5,
"include_answer": false,
"include_raw_content": false,
"include_images": false
}'
```

##

[​](#response)

Response

[​](#param-query-1)

query

string

Executed search query.

[​](#param-answer)

answer

string

LLM-generated answer only when `include_answer`is requested.

[​](#param-images)

images

object[]

List of images from image search. Returned if `include_images` is `true`. Image `url` and `description` are included if `include_image_description` is `true`. See [Images Output Object](#images-output-object).

[​](#param-results)

results

object[]

Search results.

[​](#param-response-time)

response_time

float

Request duration in seconds.

[​](#param-auto-parameters-1)

auto_parameters

object

Dictionary of automatically set parameters. Included if `auto_parameters` is `true`.

[​](#param-request-id)

request_id

string

Unique request identifier.

###

[​](#images-output-object)

Images Output Object

[​](#param-url)

url

string

Image URL.

[​](#param-description)

description

string

Image Description.

###

[​](#result-object)

Result Object

[​](#param-title)

title

string

Result title.

[​](#param-url-1)

url

string

Result URL.

[​](#param-content)

content

string

Result short snippet.

[​](#param-score)

score

float

Result relevance score.

[​](#param-raw-content)

raw_content

string

Result HTML content. Returned if `include_raw_content` is `true`.

[​](#param-favicon)

favicon

string

Site favicon URL.

[​](#param-images-1)

images

object[]

List of images from search results. Returned if `include_images` is `true`. Image `url` and `description` are included if `include_image_description` is `true`. See [Images Output Object](#images-output-object).

##

[​](#errors)

Errors

The platform may return standard HTTP errors before forwarding the request, and Tavily may return upstream errors after forwarding.

[​](#param-400)

400

status

Invalid request body or unsupported parameter value.

[​](#param-401)

401

status

Missing or invalid API key.

[​](#param-403)

403

status

Access denied by platform or upstream provider.

[​](#param-404)

404

status

Route or requested resource not found.

[​](#param-429)

429

status

Rate limit exceeded.

[​](#param-500)

500

status

Internal server error.

[​](#param-502)

502

status

Upstream provider error.

[​](#param-503)

503

status

Service unavailable.

##

[​](#notes)

Notes

- All request bodies are JSON.

- Extra Tavily parameters not listed here may be passed through.

- Response shapes can vary depending on request options.

- This document intentionally omits billing-related fields.

##

[​](#references)

References

For more details, see the [Tavily Search API reference](https://docs.tavily.com/documentation/api-reference/endpoint/search).

Last modified on June 23, 2026