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
  }
}

搜索网页，返回的排序结果里已经带好页面正文，不需要再调一次抓取。query 必填。返回 results[]，每条含 url、title、content（提取出的正文片段）、score，以及可选的 raw_content；顶层还有 query、images、response_time 和 request_id。设 include_answer 可以额外拿到一段 answer。可用 topic（general/news/finance）、time_range 或明确的 start_date/end_date 过滤，用 search_depth 在成本与深度之间取舍。实测取 2 条结果约 6 秒。开放网页检索优先选它，也是这里唯一在一次调用里同时给出排序结果和页面正文的搜索。什么时候该换：已经知道 URL —— post_tavily_extract 更便宜也更准确；查询是一段描述而不是关键词 —— post_exa_search 按语义匹配；想要一段带引用的答案而不是可遍历的列表 —— post_perplexity_sonar；要的是同行评审论文 —— post_scholar_search_scholar。

第一次用？ 把任意 MCP 客户端指向 https://mcp.aisa.one/mcp —— Claude Code、 Codex、Cursor、VS Code 都可以。鉴权走 OAuth：客户端打开浏览器，你点一次 Allow，不需要粘贴任何 key。之后智能体通过几个元工具调用所有端点： search、list_categories、get_details 和 batch_quote 免费，batch_use 按次计费。各客户端的接入步骤见通过 MCP 连接；实时工具列表和每次调用的价格见 aisa.one/zh-cn/mcp。

在你的 agent 里把这个端点跑起来 →

请求规范

方法与路径: POST /apis/v1/tavily/search
可用状态: enabled
请求 URL 模板: https://api.aisa.one/apis/v1/tavily/search
Runtime 事实版本: ea2301436db90d0b30e55885326cd5057bea93ff7d26d9bced8e1ae7f1911ef4

完整 OpenAPI 定义有效请求与价格声明（包括认证和引用的 schema）：

{
  "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"
      }
    }
  }
}

费用与请求规则

按用量计费；默认请求预估费用：$0.016 USD（不是固定价格）。声明的单位费率：每 tavily_credit $0.008 USD。最终费用以账户适用价格及实际结算为准。公开参考值不是你的账户报价或最终扣费。对于支持 X-AISA-Cost-Mode: quote 的接口，执行前请针对完整请求获取免费报价；执行后通过响应费用元数据和 Usage Logs 核对结算费用。1 USD 等于 1,000,000 个整数 micro-USD。

默认请求参考估价（USD）: 0.016
声明的单位费率（USD）: 0.008
计费单位: tavily_credit
计费依据: response_units
公开参考倍率: 1.0
结算证据来源: response_body

授权

Authorization

string

header

必填

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

请求体

application/json

query

string

必填

要使用 Tavily 执行的搜索查询。

示例:

"Who is Leo Messi?"

auto_parameters

boolean

默认值:false

根据查询内容自动配置搜索参数。

chunks_per_source

integer

默认值:3

每个来源返回的相关文本块的最大数量。

必填范围: 1 <= x <= 3

country

enum<string>

提升特定国家/地区的搜索结果。仅当 topic 为 general 时可用。

可用选项:

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>

返回指定结束日期之前的结果。

示例:

"2025-12-29"

exclude_domains

string[]

要从搜索结果中特别排除的域名列表。

Maximum array length: 150

include_answer

默认值:false

包含由 LLM 生成的答案。true 使用默认答案模式；basic 或 advanced 用于选择答案生成模式。

include_domains

string[]

搜索结果中需要明确包含的域名列表。

Maximum array length: 300

include_favicon

boolean

默认值:false

为每个结果包含 favicon URL。

include_image_descriptions

boolean

默认值:false

当 include_images 为 true 时，为每张图片添加描述性文本。

include_images

boolean

默认值:false

执行图片搜索并包含搜索结果。

include_raw_content

默认值:false

为每个搜索结果包含清理和解析后的内容。true 或 markdown 返回 Markdown；text 返回纯文本，并可能增加延迟。

include_usage

boolean

默认值:false

在响应中包含信用额度用量信息。

max_results

integer

默认值:5

返回的最大搜索结果数。

必填范围: 0 <= x <= 20

safe_search

boolean

默认值:false

从搜索结果中过滤成人或不安全内容。仅限企业版；当 search_depth 为 fast 或 ultra-fast 时不受支持。

search_depth

enum<string>

默认值:basic

控制延迟与相关性之间的权衡。advanced 以更高的延迟和成本提供最高相关性；basic 实现均衡；fast 和 ultra-fast 针对更低延迟进行优化。

可用选项:

advanced,

basic,

fast,

ultra-fast

start_date

string<date>

返回指定开始日期之后的结果。

示例:

"2025-02-09"

time_range

enum<string>

根据发布日期筛选结果的时间范围。

可用选项:

day,

week,

month,

year,

d,

w,

m,

y

topic

enum<string>

默认值:general

搜索类别。

可用选项:

general,

news,

finance

响应

搜索结果已成功返回。

answer

string | null

由 LLM 生成的简短回答。当 include_answer 为 false 或未生成回答时，此字段为 null。

images

object[]

Show child attributes

query

string

已执行的搜索查询。

request_id

string

唯一请求标识符。

response_time

number<float>

完成请求所用的时间（秒）。

results

object[]

Show child attributes

usage

object

Show child attributes

概览

模型

搜索与研究

金融与加密

社交与媒体

SEO 与网站情报

销售与邮件

出行与其他

Media Generation

Oxylabs Web API

Search Tavily Data

请求规范

费用与请求规则

授权

请求体

响应

​请求规范

​费用与请求规则

授权

请求体

响应

请求规范

费用与请求规则