Skip to content
looot docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Tavily / Search the web

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.

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.

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:

{ 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 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/<runId>.

Example input with placeholder values:

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}'
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);
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.

Was this page helpful?