POST
/
search
curl --request POST \
  --url https://api.tavily.com/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "who is Leo Messi?",
  "topic": "general",
  "search_depth": "basic",
  "max_results": 1,
  "time_range": null,
  "days": 3,
  "include_answer": true,
  "include_raw_content": false,
  "include_images": false,
  "include_image_descriptions": false,
  "include_domains": [],
  "exclude_domains": []
}'
{
  "query": "Who is Leo Messi?",
  "answer": "Lionel Messi, born in 1987, is an Argentine footballer widely regarded as one of the greatest players of his generation. He spent the majority of his career playing for FC Barcelona, where he won numerous domestic league titles and UEFA Champions League titles. Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability. He has won multiple FIFA Ballon d'Or awards, numerous La Liga titles with Barcelona, and holds the record for most goals scored in a calendar year. In 2014, he led Argentina to the World Cup final, and in 2015, he helped Barcelona capture another treble. Despite turning 36 in June, Messi remains highly influential in the sport.",
  "images": [],
  "results": [
    {
      "title": "Lionel Messi Facts | Britannica",
      "url": "https://www.britannica.com/facts/Lionel-Messi",
      "content": "Lionel Messi, an Argentine footballer, is widely regarded as one of the greatest football players of his generation. Born in 1987, Messi spent the majority of his career playing for Barcelona, where he won numerous domestic league titles and UEFA Champions League titles. Messi is known for his exceptional dribbling skills, vision, and goal",
      "score": 0.81025416,
      "raw_content": null
    }
  ],
  "response_time": "1.67"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header in the form Bearer <token>, where <token> is your Tavily API key (e.g., Bearer tvly-YOUR_API_KEY).

Body

application/json
Parameters for the Tavily Search request.
​
query
string
required

The search query to execute with Tavily.

Example:

"who is Leo Messi?"

​
topic
enum<string>
default:general

The category of the search.

Available options:
general,
news
​
search_depth
enum<string>
default:basic

The depth of the search. A basic search costs 1 API Credit, while an advanced search costs 2 API Credits.

Available options:
basic,
advanced
​
max_results
integer
default:5

The maximum number of search results to return.

Required range: 0 <= x <= 20
Example:

1

​
time_range
enum<string>

The time range back from the current date to filter results.

Available options:
day,
week,
month,
year,
d,
w,
m,
y
​
days
integer
default:3

Number of days back from the current date to include. Available only if topic is news.

Required range: x >= 0
​
include_answer
default:false

Include an LLM-generated answer to the provided query. basic or true returns a quick answer. advanced returns a more detailed answer.

​
include_raw_content
boolean
default:false

Include the cleaned and parsed HTML content of each search result.

​
include_images
boolean
default:false

Also perform an image search and include the results in the response.

​
include_image_descriptions
boolean
default:false

When include_images is true, also add a descriptive text for each image.

​
include_domains
string[]

A list of domains to specifically include in the search results.

​
exclude_domains
string[]

A list of domains to specifically exclude from the search results.

Response

200
application/json
Search results returned successfully
​
query
string

The search query that was executed.

Example:

"Who is Leo Messi?"

​
answer
string

A short answer to the user's query, generated by an LLM. Included in the response only if include_answer is requested (i.e., set to true, basic, or advanced)

Example:

"Lionel Messi, born in 1987, is an Argentine footballer widely regarded as one of the greatest players of his generation. He spent the majority of his career playing for FC Barcelona, where he won numerous domestic league titles and UEFA Champions League titles. Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability. He has won multiple FIFA Ballon d'Or awards, numerous La Liga titles with Barcelona, and holds the record for most goals scored in a calendar year. In 2014, he led Argentina to the World Cup final, and in 2015, he helped Barcelona capture another treble. Despite turning 36 in June, Messi remains highly influential in the sport."

​
images
object[]

List of query-related images. If include_image_descriptions is true, each item will have url and description.

Example:
[]
​
results
object[]

A list of sorted search results, ranked by relevancy.

​
response_time
number

Time in seconds it took to complete the request.

Example:

"1.67"

IntroductionTavily Extract