Search Tavily Data

Reference example

# Fixed reference example. Playground inputs do not update this sample.
curl --request POST \
  --url https://api.aisa.one/apis/v1/tavily/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "Who is Leo Messi?"
}'

curl --request POST \
  --url https://api.aisa.one/apis/v1/tavily/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "Who is Leo Messi?"
}
'

import requests

url = "https://api.aisa.one/apis/v1/tavily/search"

payload = { "query": "Who is Leo Messi?" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: 'Who is Leo Messi?'})
};

fetch('https://api.aisa.one/apis/v1/tavily/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/tavily/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => 'Who is Leo Messi?'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/tavily/search"

	payload := strings.NewReader("{\n  \"query\": \"Who is Leo Messi?\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/tavily/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"Who is Leo Messi?\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/tavily/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"Who is Leo Messi?\"\n}"

response = http.request(request)
puts response.read_body

{
  "answer": "<string>",
  "images": [
    {
      "description": "<string>",
      "url": "<string>"
    }
  ],
  "query": "<string>",
  "request_id": "<string>",
  "response_time": 123,
  "results": [
    {
      "content": "<string>",
      "favicon": "<string>",
      "raw_content": "<string>",
      "score": 123,
      "title": "<string>",
      "url": "<string>"
    }
  ],
  "usage": {
    "credits": 123
  }
}

POST

https://api.aisa.one

apis

tavily

Reference example

# Fixed reference example. Playground inputs do not update this sample.
curl --request POST \
  --url https://api.aisa.one/apis/v1/tavily/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "Who is Leo Messi?"
}'

curl --request POST \
  --url https://api.aisa.one/apis/v1/tavily/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "Who is Leo Messi?"
}
'

import requests

url = "https://api.aisa.one/apis/v1/tavily/search"

payload = { "query": "Who is Leo Messi?" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: 'Who is Leo Messi?'})
};

fetch('https://api.aisa.one/apis/v1/tavily/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/tavily/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => 'Who is Leo Messi?'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/tavily/search"

	payload := strings.NewReader("{\n  \"query\": \"Who is Leo Messi?\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/tavily/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"Who is Leo Messi?\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/tavily/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"Who is Leo Messi?\"\n}"

response = http.request(request)
puts response.read_body

{
  "answer": "<string>",
  "images": [
    {
      "description": "<string>",
      "url": "<string>"
    }
  ],
  "query": "<string>",
  "request_id": "<string>",
  "response_time": 123,
  "results": [
    {
      "content": "<string>",
      "favicon": "<string>",
      "raw_content": "<string>",
      "score": 123,
      "title": "<string>",
      "url": "<string>"
    }
  ],
  "usage": {
    "credits": 123
  }
}

Search the web and get back ranked results with the page text already extracted, so there is no second call to fetch content. query is required. Returns results[] with url, title, content (the extracted excerpt), score and optionally raw_content, alongside query, images, response_time and request_id; set include_answer to also get a one-paragraph answer. Filter with topic (general/news/finance), time_range or explicit start_date/end_date, and trade cost against depth with search_depth. Measured at roughly 6 seconds for 2 results. This is the default choice for open-web research, and the only search here that returns ranked results and page text in one call. Reach past it when: you already know the URLs — post_tavily_extract is cheaper and exact; the query is a description rather than keywords — post_exa_search matches on meaning; you want a written answer rather than a list to iterate — post_perplexity_sonar; you want peer-reviewed papers — post_scholar_search_scholar.

First time? Point any MCP client at https://mcp.aisa.one/mcp — Claude Code, Codex, Cursor, VS Code and the rest. Authorization is OAuth: the client opens a browser, you click Allow once, and there is no key to paste. Your agent then reaches every endpoint through a few meta tools: search, list_categories, get_details and batch_quote are free, batch_use is billed per call. Setup per client is in Connect via MCP; the live tool list and what each call costs are on aisa.one/mcp.

Set this endpoint up in your agent →

Request contract

Method and path: POST /apis/v1/tavily/search
Availability: enabled
Request URL template: https://api.aisa.one/apis/v1/tavily/search
Runtime facts: ea2301436db90d0b30e55885326cd5057bea93ff7d26d9bced8e1ae7f1911ef4

Complete OpenAPI definition Effective request and pricing declaration (including authentication and referenced schemas):

{
  "operationId": "post_tavily_search",
  "method": "POST",
  "path": "/apis/v1/tavily/search",
  "servers": [
    {
      "url": "https://api.aisa.one"
    }
  ],
  "parameters": [],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "properties": {
            "auto_parameters": {
              "default": false,
              "description": "Automatically configure search parameters based on query content.",
              "type": "boolean"
            },
            "chunks_per_source": {
              "default": 3,
              "description": "Maximum number of relevant chunks returned per source.",
              "maximum": 3,
              "minimum": 1,
              "type": "integer"
            },
            "country": {
              "description": "Boost search results from a specific country. Available only when topic is general.",
              "enum": [
                "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"
              ],
              "type": "string"
            },
            "end_date": {
              "description": "Return results before the specified end date.",
              "example": "2025-12-29",
              "format": "date",
              "type": "string"
            },
            "exclude_domains": {
              "description": "List of domains to specifically exclude from the search results.",
              "items": {
                "type": "string"
              },
              "maxItems": 150,
              "type": "array"
            },
            "include_answer": {
              "default": false,
              "description": "Include an LLM-generated answer. true uses the default answer mode; basic or advanced selects the answer generation mode.",
              "oneOf": [
                {
                  "type": "boolean"
                },
                {
                  "enum": [
                    "basic",
                    "advanced"
                  ],
                  "type": "string"
                }
              ]
            },
            "include_domains": {
              "description": "List of domains to specifically include in the search results.",
              "items": {
                "type": "string"
              },
              "maxItems": 300,
              "type": "array"
            },
            "include_favicon": {
              "default": false,
              "description": "Include the favicon URL for each result.",
              "type": "boolean"
            },
            "include_image_descriptions": {
              "default": false,
              "description": "Add descriptive text for each image when include_images is true.",
              "type": "boolean"
            },
            "include_images": {
              "default": false,
              "description": "Perform an image search and include results.",
              "type": "boolean"
            },
            "include_raw_content": {
              "default": false,
              "description": "Include cleaned and parsed content for each search result. true or markdown returns markdown; text returns plain text and may increase latency.",
              "oneOf": [
                {
                  "type": "boolean"
                },
                {
                  "enum": [
                    "markdown",
                    "text"
                  ],
                  "type": "string"
                }
              ]
            },
            "include_usage": {
              "default": false,
              "description": "Include credit usage information in the response.",
              "type": "boolean"
            },
            "max_results": {
              "default": 5,
              "description": "Maximum number of search results to return.",
              "maximum": 20,
              "minimum": 0,
              "type": "integer"
            },
            "query": {
              "description": "The search query to execute with Tavily.",
              "example": "Who is Leo Messi?",
              "type": "string"
            },
            "safe_search": {
              "default": false,
              "description": "Filter out adult or unsafe content from search results. Enterprise only; not supported when search_depth is fast or ultra-fast.",
              "type": "boolean"
            },
            "search_depth": {
              "default": "basic",
              "description": "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.",
              "enum": [
                "advanced",
                "basic",
                "fast",
                "ultra-fast"
              ],
              "type": "string"
            },
            "start_date": {
              "description": "Return results after the specified start date.",
              "example": "2025-02-09",
              "format": "date",
              "type": "string"
            },
            "time_range": {
              "description": "Time range to filter results based on publish date.",
              "enum": [
                "day",
                "week",
                "month",
                "year",
                "d",
                "w",
                "m",
                "y"
              ],
              "type": "string"
            },
            "topic": {
              "default": "general",
              "description": "Category of the search.",
              "enum": [
                "general",
                "news",
                "finance"
              ],
              "type": "string"
            }
          },
          "required": [
            "query"
          ],
          "type": "object"
        }
      }
    },
    "required": true
  },
  "x-aisa-status": "enabled",
  "x-aisa-pricing": {
    "cost_contract": "response_units",
    "customer_multiplier": 1.0,
    "customer_pricing": "provider_cost_multiplier",
    "default_request_estimate_usd": 0.016,
    "estimate_source": "profile_seed",
    "evidence_source": "response_body",
    "unit": "tavily_credit",
    "unit_rate_usd": 0.008
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  }
}

Cost and request rules

Usage-based billing; Default request estimate: $0.016 USD (not a fixed price). Declared unit rate: $0.008 USD per tavily_credit. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.

Default request reference estimate (USD): 0.016
Declared unit rate (USD): 0.008
Billing unit: tavily_credit
Cost contract: response_units
Published reference multiplier: 1.0
Settlement evidence source: response_body

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

query

string

required

The search query to execute with Tavily.

Example:

"Who is Leo Messi?"

auto_parameters

boolean

default:false

Automatically configure search parameters based on query content.

chunks_per_source

integer

default:3

Maximum number of relevant chunks returned per source.

Required range: 1 <= x <= 3

country

enum<string>

Boost search results from a specific country. Available only when topic is general.

Available options:

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

end_date

string<date>

Return results before the specified end date.

Example:

"2025-12-29"

exclude_domains

string[]

List of domains to specifically exclude from the search results.

Maximum array length: 150

include_answer

default:false

Include an LLM-generated answer. true uses the default answer mode; basic or advanced selects the answer generation mode.

include_domains

string[]

List of domains to specifically include in the search results.

Maximum array length: 300

include_favicon

boolean

default:false

Include the favicon URL for each result.

include_image_descriptions

boolean

default:false

Add descriptive text for each image when include_images is true.

include_images

boolean

default:false

Perform an image search and include results.

include_raw_content

default:false

Include cleaned and parsed content for each search result. true or markdown returns markdown; text returns plain text and may increase latency.

include_usage

boolean

default:false

Include credit usage information in the response.

max_results

integer

default:5

Maximum number of search results to return.

Required range: 0 <= x <= 20

safe_search

boolean

default:false

Filter out adult or unsafe content from search results. Enterprise only; not supported when search_depth is fast or ultra-fast.

search_depth

enum<string>

default:basic

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.

Available options:

advanced,

basic,

fast,

ultra-fast

start_date

string<date>

Return results after the specified start date.

Example:

"2025-02-09"

time_range

enum<string>

Time range to filter results based on publish date.

Available options:

day,

week,

month,

year,

d,

w,

m,

y

topic

enum<string>

default:general

Category of the search.

Available options:

general,

news,

finance

Response

Search results returned successfully.

answer

string | null

A short LLM-generated answer. Present as null when include_answer is false or no answer is generated.

images

object[]

Show child attributes

query

string

The search query that was executed.

request_id

string

Unique request identifier.

response_time

number<float>

Time in seconds it took to complete the request.

results

object[]

Show child attributes

usage

object

Show child attributes

Overview

Models

Search & Research

Finance & Crypto

Social & Media

SEO & Web Intel

Sales & Email

Travel & Other

Search Tavily Data

Request contract

Cost and request rules

Authorizations

Body

Response

​Request contract

​Cost and request rules

Authorizations

Body

Response

Request contract

Cost and request rules