Data API / Tavily / Search

Tavily Search

Search the web and return ranked results with titles, URLs and content snippets. query is required. Use max_results to control the number of results and search_depth to select the search mode. Additional answer, images and raw content are returned only when requested. Set include_usage to receive resource usage information; usage.credits is not a Felo charge.

Parameters

No path, query, or header parameters.

Request body

querystringRequired
The search query to execute with Tavily.
search_depthstringOptional
Allowed values: advanced · basic · fast · ultra-fast
Controls the latency vs. relevance tradeoff. advanced gives the highest relevance with higher latency and cost; basic is balanced; fast and ultra-fast optimize for lower latency.
chunks_per_sourceintegerOptional
Maximum number of relevant chunks returned per source.
max_resultsintegerOptional
Maximum number of search results to return.
topicstringOptional
Allowed values: general · news · finance
Category of the search.
time_rangestringOptional
Allowed values: day · week · month · year · d · w · m · y
Time range to filter results based on publish date.
start_datestringOptional
Return results after the specified start date.
end_datestringOptional
Return results before the specified end date.
include_answerOptional
Allowed values: basic · advanced
Include an LLM-generated answer. true uses the default answer mode; basic or advanced selects the answer generation mode.
include_raw_contentOptional
Allowed values: markdown · text
Include cleaned and parsed content for each search result. true or markdown returns markdown; text returns plain text and may increase latency.
include_imagesbooleanOptional
Perform an image search and include results.
include_image_descriptionsbooleanOptional
Add descriptive text for each image when include_images is true.
safe_searchbooleanOptional
Filter out adult or unsafe content from search results. Enterprise only; not supported when search_depth is fast or ultra-fast.
include_faviconbooleanOptional
Include the favicon URL for each result.
include_domainsstring[]Optional
List of domains to specifically include in the search results.
exclude_domainsstring[]Optional
List of domains to specifically exclude from the search results.
countrystringOptional
Allowed values: 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 · slovakia · slovenia · somalia · south africa · south korea · south sudan · spain · sri lanka · sudan · sweden · switzerland · syria · taiwan · tajikistan · tanzania · thailand · togo · trinidad and tobago · tunisia · turkey · turkmenistan · uganda · ukraine · united arab emirates · united kingdom · united states · uruguay · uzbekistan · venezuela · vietnam · yemen · zambia · zimbabwe
Boost search results from a specific country. Available only when topic is general.
auto_parametersbooleanOptional
Automatically configure search parameters based on query content.
include_usagebooleanOptional
Include resource usage information in the response. This is not Felo billing information.

Example request

curl -X POST "https://openapi.felo.ai/v1/beta/tavily/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "<string>",
  "search_depth": "<string>",
  "chunks_per_source": 0,
  "max_results": 0,
  "topic": "<string>",
  "time_range": "<string>",
  "start_date": "<string>",
  "end_date": "<string>"
}'

Response

Example response

{
  "query": "Python official documentation",
  "answer": null,
  "images": [],
  "results": [
    {
      "title": "Python Documentation",
      "url": "https://docs.python.org/3/",
      "content": "Documentation for the Python programming language.",
      "score": 0.98,
      "raw_content": null
    }
  ],
  "response_time": 1.2,
  "usage": {
    "credits": 1
  },
  "request_id": "example-search-request"
}

Response fields

querystringOptional
The search query that was executed.
answerOptional
A short LLM-generated answer. Present as null when include_answer is false or no answer is generated.
imagesobject[]Optional
urlstringOptional
Image URL.
descriptionstringOptional
Image description.
resultsobject[]Optional
titlestringOptional
Title of the search result.
urlstringOptional
URL of the search result.
contentstringOptional
Content snippet of the search result.
scorenumberOptional
Relevance score of the search result.
faviconOptional
Favicon URL of the search result.
raw_contentOptional
Cleaned and parsed source content. Null unless include_raw_content is requested or no raw content is available.
response_timenumberOptional
Time in seconds it took to complete the request.
usageobjectOptional
creditsintegerOptional
Resource units consumed by this request, not USD or Felo credits.
request_idstringOptional
Unique request identifier.