请求体

• querystring必填

  The search query to execute with Tavily.

• search_depthstring可选
  默认 "basic"

  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 latency while maintaining good relevance. Returns multiple semantically relevant snippets per URL (configurable via `chunks_per_source`). - `ultra-fast`: Minimizes latency above all else. Best for time-critical use cases. Returns one NLP summary per URL. **Cost**: - `basic`, `fast`, `ultra-fast`: 1 API Credit - `advanced`: 2 API Credits See [Search Best Practices](/documentation/best-practices/best-practices-search#search-depth) for guidance on choosing the right search depth.

  取值 advancedbasicfastultra-fast
• chunks_per_sourceinteger可选
  默认 3

  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`.

• max_resultsinteger可选
  默认 10

  The maximum number of search results to return.

• topicstring可选
  默认 "general"

  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.

  取值 generalnewsfinance
• time_rangestring可选
  默认 null

  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. By default, results with no detectable published date are not removed; set `filter_by_published_date` to `true` to remove them.

  取值 dayweekmonthyeardwmy
• start_datestring可选
  默认 null

  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. By default, results with no detectable published date are not removed; set `filter_by_published_date` to `true` to remove them.

• end_datestring可选
  默认 null

  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. By default, results with no detectable published date are not removed; set `filter_by_published_date` to `true` to remove them.

• include_published_dateboolean可选
  默认 false

  Include a `published_date` field in each result. The date is Tavily's best estimate of when the source was published or last updated, so it can be later than the original publish date. Results with no detectable date return `null`. Automatically enabled when `topic` is `news`. **Note**: this feature is currently in beta.

• filter_by_published_dateboolean可选
  默认 false

  Remove results whose published date falls outside the `time_range`, `start_date`, or `end_date` window. Results with no detectable published date are also removed. Setting this to `true` also enables `include_published_date`. If you want date-window filtering but don't want to lose sources without a detectable date, leave this `false` and set `include_published_date: true` together with a date range instead.

• ▸ 更多参数（15）

  • include_answerboolean | string可选
    默认 false

    Include an LLM-generated answer to the provided query. `basic` or `true` returns a quick answer. `advanced` returns a more detailed answer.

  • include_raw_contentboolean | string可选
    默认 false

    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_imagesboolean可选
    默认 false

    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_image_descriptionsboolean可选
    默认 false

    When `include_images` is `true`, also add a descriptive text for each image.

  • include_faviconboolean可选
    默认 false

    Whether to include the favicon URL for each result.

  • include_domainsarray可选
    默认 []

    A list of domains to specifically include in the search results. Maximum 300 domains.

  • exclude_domainsarray可选
    默认 []

    A list of domains to specifically exclude from the search results. Maximum 150 domains.

  • include_domains_modestring可选
    默认 null

    Controls how `include_domains` is applied. `restrict` limits results to only the listed domains. `prefer` 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.

    取值 restrictprefer
  • countrystring可选
    默认 null

    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`.

    取值 afghanistanalbaniaalgeriaandorraangolaargentinaarmeniaaustraliaaustriaazerbaijanbahamasbahrainbangladeshbarbadosbelarusbelgiumbelizebeninbhutanboliviabosnia and herzegovinabotswanabrazilbruneibulgariaburkina fasoburundicambodiacamerooncanadacape verdecentral african republicchadchilechinacolombiacomoroscongocosta ricacroatiacubacyprusczech republicdenmarkdjiboutidominican republicecuadoregyptel salvadorequatorial guineaeritreaestoniaethiopiafijifinlandfrancegabongambiageorgiagermanyghanagreeceguatemalaguineahaitihondurashungaryicelandindiaindonesiairaniraqirelandisraelitalyjamaicajapanjordankazakhstankenyakuwaitkyrgyzstanlatvialebanonlesotholiberialibyaliechtensteinlithuanialuxembourgmadagascarmalawimalaysiamaldivesmalimaltamauritaniamauritiusmexicomoldovamonacomongoliamontenegromoroccomozambiquemyanmarnamibianepalnetherlandsnew zealandnicaraguanigernigerianorth koreanorth macedonianorwayomanpakistanpanamapapua new guineaparaguayperuphilippinespolandportugalqatarromaniarussiarwandasaudi arabiasenegalserbiasingaporeslovakiasloveniasomaliasouth africasouth koreasouth sudanspainsri lankasudanswedenswitzerlandsyriataiwantajikistantanzaniathailandtogotrinidad and tobagotunisiaturkeyturkmenistanugandaukraineunited arab emiratesunited kingdomunited statesuruguayuzbekistanvenezuelavietnamyemenzambiazimbabwe
  • languagestring可选
    默认 null

    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.

  • filter_by_languageboolean可选
    默认 false

    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.

  • auto_parametersboolean可选
    默认 false

    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 request. To avoid the extra cost, you can explicitly set `search_depth` to `basic`.

  • exact_matchboolean可选
    默认 false

    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.

  • include_usageboolean可选
    默认 false

    Whether to include credit usage information in the response.

  • safe_searchboolean可选
    默认 false

    Whether to filter out adult or unsafe content from results. Not supported for `fast` or `ultra-fast` search depths.

返回

200

错误按 Tavily 格式返回，参见 错误码

请求体

• querystring可选

  User intent for reranking extracted content chunks. When provided, chunks are reranked based on relevance to this query.

• urlsstring | array必填
• chunks_per_sourceinteger可选
  默认 3

  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 `raw_content` length. Chunks will appear in the `raw_content` field as: `<chunk 1> [...] <chunk 2> [...] <chunk 3>`. Available only when `query` is provided. Must be between 1 and 5.

• extract_depthstring可选
  默认 "basic"

  The depth of the extraction process. `advanced` extraction retrieves more data, including tables and embedded content, with higher success but may increase latency.`basic` extraction costs 1 credit per 5 successful URL extractions, while `advanced` extraction costs 2 credits per 5 successful URL extractions.

  取值 basicadvanced
• include_imagesboolean可选
  默认 false

  Include a list of images extracted from the URLs in the response. Default is false.

• include_faviconboolean可选
  默认 false

  Whether to include the favicon URL for each result.

• formatstring可选
  默认 "markdown"

  The format of the extracted web page content. `markdown` returns content in markdown format. `text` returns plain text and may increase latency.

  取值 markdowntext
• timeoutnumber可选
  默认 "None"

  Maximum time in seconds to wait for the URL extraction before timing out. Must be between 1.0 and 60.0 seconds. If not specified, default timeouts are applied based on extract_depth: 10 seconds for basic extraction and 30 seconds for advanced extraction.

• include_usageboolean可选
  默认 false

  Whether to include credit usage information in the response. `NOTE:`The value may be 0 if the total successful URL extractions has not yet reached 5 calls. See our [Credits & Pricing documentation](https://docs.tavily.com/documentation/api-credits) for details.

返回

200

错误按 Tavily 格式返回，参见 错误码

请求体

• urlstring必填

  The root URL to begin the crawl.

• limitinteger可选
  默认 50

  Total number of links the crawler will process before stopping.

• instructionsstring可选

  Natural language instructions for the crawler. When specified, the mapping cost increases to 2 API credits per 10 successful pages instead of 1 API credit per 10 pages.

• chunks_per_sourceinteger可选
  默认 3

  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 `raw_content` length. Chunks will appear in the `raw_content` field as: `<chunk 1> [...] <chunk 2> [...] <chunk 3>`. Available only when `instructions` are provided. Must be between 1 and 5.

• max_depthinteger可选
  默认 1

  Max depth of the crawl. Defines how far from the base URL the crawler can explore.

• max_breadthinteger可选
  默认 20

  Max number of links to follow per level of the tree (i.e., per page).

• select_pathsarray可选
  默认 null

  Regex patterns to select only URLs with specific path patterns (e.g., `/docs/.*`, `/api/v1.*`).

• select_domainsarray可选
  默认 null

  Regex patterns to select crawling to specific domains or subdomains (e.g., `^docs\.example\.com$`).

• exclude_pathsarray可选
  默认 null

  Regex patterns to exclude URLs with specific path patterns (e.g., `/private/.*`, `/admin/.*`).

• exclude_domainsarray可选
  默认 null

  Regex patterns to exclude specific domains or subdomains from crawling (e.g., `^private\.example\.com$`).

• ▸ 更多参数（7）

  • allow_externalboolean可选
    默认 true

    Whether to include external domain links in the final results list.

  • include_imagesboolean可选
    默认 false

    Whether to include images in the crawl results.

  • extract_depthstring可选
    默认 "basic"

    Advanced extraction retrieves more data, including tables and embedded content, with higher success but may increase latency. `basic` extraction costs 1 credit per 5 successful extractions, while `advanced` extraction costs 2 credits per 5 successful extractions.

    取值 basicadvanced
  • formatstring可选
    默认 "markdown"

    The format of the extracted web page content. `markdown` returns content in markdown format. `text` returns plain text and may increase latency.

    取值 markdowntext
  • include_faviconboolean可选
    默认 false

    Whether to include the favicon URL for each result.

  • timeoutnumber可选
    默认 150

    Maximum time in seconds to wait for the crawl operation before timing out. Must be between 10 and 150 seconds.

  • include_usageboolean可选
    默认 false

    Whether to include credit usage information in the response. `NOTE:`The value may be 0 if the total use of /extract and /map have not yet reached minimum requirements. See our [Credits & Pricing documentation](https://docs.tavily.com/documentation/api-credits) for details.

返回

200

调用前要求账户余额大于 0；按 Tavily 返回的 usage.credits 计费，每 credit $0.01；Tavily 未返回用量时，按本次请求可能消耗的上限计费。

错误按 Tavily 格式返回，参见 错误码

请求体

• urlstring必填

  The root URL to begin the mapping.

• limitinteger可选
  默认 50

  Total number of links the crawler will process before stopping.

• instructionsstring可选
  默认 null

  Natural language instructions for the crawler. When specified, the cost increases to 2 API credits per 10 successful pages instead of 1 API credit per 10 pages.

• max_depthinteger可选
  默认 1

  Max depth of the mapping. Defines how far from the base URL the crawler can explore.

• max_breadthinteger可选
  默认 20

  Max number of links to follow per level of the tree (i.e., per page).

• select_pathsarray可选
  默认 null

  Regex patterns to select only URLs with specific path patterns (e.g., `/docs/.*`, `/api/v1.*`).

• select_domainsarray可选
  默认 null

  Regex patterns to select crawling to specific domains or subdomains (e.g., `^docs\.example\.com$`).

• exclude_pathsarray可选
  默认 null

  Regex patterns to exclude URLs with specific path patterns (e.g., `/private/.*`, `/admin/.*`).

• exclude_domainsarray可选
  默认 null

  Regex patterns to exclude specific domains or subdomains from crawling (e.g., `^private\.example\.com$`).

• allow_externalboolean可选
  默认 true

  Whether to include external domain links in the final results list.

• ▸ 更多参数（2）

  • timeoutnumber可选
    默认 150

    Maximum time in seconds to wait for the map operation before timing out. Must be between 10 and 150 seconds.

  • include_usageboolean可选
    默认 false

    Whether to include credit usage information in the response.`NOTE:`The value may be 0 if the total successful pages mapped has not yet reached 10 calls. See our [Credits & Pricing documentation](https://docs.tavily.com/documentation/api-credits) for details.

返回

200

调用前要求账户余额大于 0；按 Tavily 返回的 usage.credits 计费，每 credit $0.01；Tavily 未返回用量时，按本次请求可能消耗的上限计费。

错误按 Tavily 格式返回，参见 错误码

请求体

• request_idstring可选

  The search request to give feedback on, as returned in the `request_id` field of the search response. When provided, the feedback applies to this request.

• session_idstring可选

  The session to give feedback on — the value you sent in the `X-Session-Id` header. When `request_id` is omitted, the feedback applies to the whole session. Optional if `request_id` is provided.

• agent_scorenumber | string可选

  Overall score for how relevant and useful the results were for your task.

• human_scorenumber | string可选

  Feedback from your end user, if you collect it.

• extra_scoresarray可选

  Additional labeled scores for the dimensions you care about.

  ▸ 展开子字段（2）

  • labelstring必填

    Name of the dimension being scored.

  • valuenumber | string必填

    A numeric score, or a short string label (max 64 characters).

• commentstring可选

  Free-text explanation of the feedback.

• response_deliveredstring可选

  The final answer you produced using the results.

• used_idsarray可选

  IDs of the results you actually used in your answer. Alternative to `used_urls`.

• used_urlsarray可选

  URLs of the results you actually used in your answer. Alternative to `used_ids`.

• used_citationsarray可选

  The specific content snippets you quoted from the results.

• ▸ 更多参数（1）

  • urls_scoresarray可选

    Per-result feedback. Identify each result by `id` or `url`.

    ▸ 展开子字段（5）

    • idstring可选

      The `id` of the result, as returned in the search response.

    • urlstring可选

      The URL of the result. Use instead of `id` when you don't have the result ID.

    • agent_scorenumber | string可选

      Score for this specific result.

    • scoresarray可选

      Additional labeled scores for this result.

    • commentstring可选

      Free-text explanation of the feedback on this result.

返回

200

原样转发给 Tavily，不计费（Tavily 官方定价未对反馈单独计费）。

错误按 Tavily 格式返回，参见 错误码