> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novita.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tavily Search

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

All endpoints require platform API authentication.

**Content-Type** `string` *required*

Use `application/json`.

**Authorization** `string` *required*

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

## Request Body

**query** `string` *required*

Search query. Minimum length is 1.

**search\_depth** `string[]`

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

**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`.

**max\_results** `integer`

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

**topic** `string[]`

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

**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`.

**start\_date** `string`

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

**end\_date** `string`

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

**include\_answer** `boolean | string[]`

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

**include\_raw\_content** `boolean | string[]`

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

**include\_images** `boolean `

Returns a list of images along with the response.

**include\_images\_descriptions** `boolean `

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

**include\_favicon** `boolean `

Include favicon URL from result.

**include\_domains** `string[] `

Restrict results to these domains. Maximum 300 domains.

**exclude\_domains** `string[] `

Exclude results from these domains. Maximum 150 domains.

**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`.

**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.

**exact\_match** `boolean`

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

## Request Example

```bash theme={"system"}
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

**query** `string`

Executed search query.

**answer** `string`

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

**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).

**results** `object[]`

Search results.

**response\_time** `float`

Request duration in seconds.

**auto\_parameters** `object`

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

**request\_id** `string`

Unique request identifier.

### Images Output Object

**url** `string`

Image URL.

**description** `string`

Image Description.

### Result Object

**title** `string`

Result title.

**url** `string`

Result URL.

**content** `string`

Result short snippet.

**score** `float`

Result relevance score.

**raw\_content** `string`

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

**favicon** `string`

Site favicon URL.

**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

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

**400** `status`

Invalid request body or unsupported parameter value.

**401** `status`

Missing or invalid API key.

**403** `status`

Access denied by platform or upstream provider.

**404** `status`

Route or requested resource not found.

**429** `status`

Rate limit exceeded.

**500** `status`

Internal server error.

**502** `status`

Upstream provider error.

**503** `status`

Service unavailable.

## 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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.