--- title: "Tavily / Search the web" description: "Tavily Search and Extract API tool tavily-search on looot: input fields, $0.008 per call, output shape, and code to run it with curl, JavaScript or Python." sidebar: hidden: true --- {/* Generated by scripts/generate-api-reference.mjs from data/api-reference.json. Do not edit. */} Searches the web. Send query; search_depth, topic, time_range, max_results and include_answer refine it. Returns results with title, URL, content and score, plus an answer when asked. Charged per search. - **Tool id:** `tavily-search` - **Provider:** [Tavily Search and Extract API](/providers/tavily) - **Job:** [Search the web and get ranked results](/reference/jobs/web-search) (`web.search`) - **Price:** $0.008 per call. A call that fails at the provider costs $0. ## Inputs | Name | Type | Required | Description | | --- | --- | --- | --- | | `auto_parameters` | boolean | no | When `auto_parameters` is enabled, Tavily automatically configures search parameters based on your query's content and intent. You can still set other parameters manually, and your explicit values will override the automatic ones. The parameters `include_answer`, `include_raw_content`, and `max_results` must always be set manually, as they directly affect response size. Note: `search_depth` may be automatically set to advanced when it's likely to improve results. This uses 2 API credits per r... | | `chunks_per_source` | integer | no | Chunks are short content snippets (maximum 500 characters each) pulled directly from the source. Use `chunks_per_source` to define the maximum number of relevant chunks returned per source and to control the `content` length. Chunks will appear in the `content` field as: `<chunk 1> [...] <chunk 2> [...] <chunk 3>`. Available when `search_depth` is `advanced`, `basic` or `fast`. | | `country` | string | no | Boost search results from a specific country. This will prioritize content from the selected country in the search results. Available only if topic is `general`. | | `end_date` | string | no | Will return all results before the specified end date based on publish date or last updated date. Required to be written in the format YYYY-MM-DD. Example: "2025-12-29" | | `exact_match` | boolean | no | Ensure that only search results containing the exact quoted phrase(s) in the query are returned, bypassing synonyms or semantic variations. Wrap target phrases in quotes within your query (e.g. `"John Smith" CEO Acme Corp`). Punctuation is typically ignored inside quotes. | | `exclude_domains` | array | no | A list of domains to specifically exclude from the search results. Maximum 150 domains. | | `filter_by_language` | boolean | no | Strictly filter out search results that don't match the `language` parameter, instead of only boosting them in ranking. Requires `language` to be set; returns a 400 error otherwise. | | `include_answer` | string | no | Include an LLM-generated answer to the provided query. `basic` or `true` returns a quick answer. `advanced` returns a more detailed answer. | | `include_domains` | array | no | A list of domains to specifically include in the search results. Maximum 300 domains. | | `include_domains_mode` | string | no | Controls how `include_domains` is applied. `filter` restricts results to only the listed domains. `boost` also searches the rest of the web, so results outside `include_domains` can still surface, rather than excluding them. Requires `include_domains` to be set; returns a 400 error otherwise. | | `include_favicon` | boolean | no | Whether to include the favicon URL for each result. | | `include_image_descriptions` | boolean | no | When `include_images` is `true`, also add a descriptive text for each image. | | `include_images` | boolean | no | Include images in the response. Returns both a top-level `images` list of query-related images and an `images` array inside each result object with images extracted from that specific source. | | `include_raw_content` | string | no | Include the cleaned and parsed HTML content of each search result. `markdown` or `true` returns search result content in markdown format. `text` returns the plain text from the results and may increase latency. | | `include_usage` | boolean | no | Whether to include credit usage information in the response. | | `language` | string | no | Boost search results in a specific language. Accepts an ISO 639-1 code (e.g. `en`, `fr`, `zh-cn`) or an English language name (e.g. `english`, `french`). By default this only boosts matching-language results in ranking; pass `filter_by_language: true` to strictly filter out non-matching results instead. For best results, write your `query` in the same language you set here. Example: "en" | | `max_results` | integer | no | The maximum number of search results to return. Example: 1 | | `query` | string | yes | The search query to execute with Tavily. Example: "who is Leo Messi?" | | `safe_search` | boolean | no | Whether to filter out adult or unsafe content from results. Not supported for `fast` or `ultra-fast` search depths. | | `search_depth` | string | no | Controls the latency vs. relevance tradeoff and how `results[].content` is generated: - `advanced`: Highest relevance with increased latency. Best for detailed, high-precision queries. Returns multiple semantically relevant snippets per URL (configurable via `chunks_per_source`). - `basic`: A balanced option for relevance and latency. Ideal for general-purpose searches. Returns multiple semantically relevant snippets per URL (configurable via `chunks_per_source`). - `fast`: Prioritizes lower... | | `start_date` | string | no | Will return all results after the specified start date based on publish date or last updated date. Required to be written in the format YYYY-MM-DD. Example: "2025-02-09" | | `time_range` | string | no | The time range back from the current date to filter results based on publish date or last updated date. Useful when looking for sources that have published or updated data. | | `topic` | string | no | The category of the search.`news` is useful for retrieving real-time updates, particularly about politics, sports, and major current events covered by mainstream media sources. `general` is for broader, more general-purpose searches that may include a wide range of sources. | ## Output Shape of the run's `result`, checked against 2 real answers: ```txt { query, answer, images: unknown[], results: { id, url, score, title, content, r... ... ``` The shape is cut here. Signed in, `looot inspect tavily-search` prints all of it. ## Run it Every call needs your API token in `LOOOT_TOKEN`; [Sign in](/get-started/sign-in#use-the-token-in-scripts-and-agents) shows how to get one. Each run also needs a new idempotency key, so a retry never pays twice. With `wait: 30` the answer comes back inline when the run ends within 30 seconds. Otherwise you get the running run back: poll `GET /v1/runs/`. Example input with placeholder values: ```bash curl curl -X POST "https://api.looot.ai/v1/runs" \ -H "Authorization: Bearer $LOOOT_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"endpointId":"tavily-search","input":{"query":"who is Leo Messi?","end_date":"2025-12-29","language":"en","start_date":"2025-02-09","max_results":1},"wait":30}' ``` ```js JavaScript const response = await fetch("https://api.looot.ai/v1/runs", { method: "POST", headers: { Authorization: `Bearer ${process.env.LOOOT_TOKEN}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID(), }, body: JSON.stringify({ endpointId: "tavily-search", input: { query: "who is Leo Messi?", end_date: "2025-12-29", language: "en", start_date: "2025-02-09", max_results: 1, }, wait: 30, }), }); const run = await response.json(); console.log(run.status, run.result); ``` ```python Python import os import uuid import requests response = requests.post( "https://api.looot.ai/v1/runs", headers={ "Authorization": f"Bearer {os.environ['LOOOT_TOKEN']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "endpointId": "tavily-search", "input": { "query": "who is Leo Messi?", "end_date": "2025-12-29", "language": "en", "start_date": "2025-02-09", "max_results": 1, }, "wait": 30, }, timeout=90, ) run = response.json() print(run["status"], run.get("result")) ``` To let looot pick among every provider of this job instead, send `job:web.search` as `endpointId`; see [the job page](/reference/jobs/web-search).