---
title: "Search for data based on a query"
method: POST
path: "/search"
---

# Search for data based on a query

`POST /search`

Execute a search query using Tavily Search.

## Request body

- object
  - `query` string, required — The search query to execute with Tavily.
  - `search_depth` 'advanced' | 'basic' | 'fast' | 'ultra-fast' — 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 one NLP summary per URL. - `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.
  - `chunks_per_source` integer — 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 only when `search_depth` is `advanced`.
  - `max_results` integer — The maximum number of search results to return.
  - `topic` 'general' | 'news' | 'finance' — 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.
  - `time_range` 'day' | 'week' | 'month' | 'year' | 'd' | 'w' | 'm' | 'y' — 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.
  - `start_date` string — 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
  - `end_date` string — 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
  - `include_answer` union — Include an LLM-generated answer to the provided query. `basic` or `true` returns a quick answer. `advanced` returns a more detailed answer.
    - boolean
    - 'basic' | 'advanced'
  - `include_raw_content` union — 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.
    - boolean
    - 'markdown' | 'text'
  - `include_images` boolean — 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_descriptions` boolean — When `include_images` is `true`, also add a descriptive text for each image.
  - `include_favicon` boolean — Whether to include the favicon URL for each result.
  - `include_domains` string[] — A list of domains to specifically include in the search results. Maximum 300 domains.
  - `exclude_domains` string[] — A list of domains to specifically exclude from the search results. Maximum 150 domains.
  - `country` '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' — 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`.
  - `auto_parameters` boolean — 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_match` boolean — 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_usage` boolean — Whether to include credit usage information in the response.
  - `safe_search` boolean — 🔒 Enterprise only. whether to filter out adult or unsafe content from results. Not supported for `fast` or `ultra-fast` search depths.

## Response `200`

Search results returned successfully

- object
  - `query` string, required — The search query that was executed.
  - `answer` string, required — A short answer to the user's query, generated by an LLM. Included in the response only if `include_answer` is requested (i.e., set to `true`, `basic`, or `advanced`)
  - `images` object[], required — A list of query-related images from image search. If `include_image_descriptions` is true, each item will have `url` and `description`. Note: per-result images are also returned inside each result object's `images` field.
    - `url` string
    - `description` string
  - `results` object[], required — A list of sorted search results, ranked by relevancy.
    - `title` string — The title of the search result.
    - `url` string — The URL of the search result.
    - `content` string — A short description of the search result.
    - `score` number, float — The relevance score of the search result.
    - `raw_content` string — The cleaned and parsed HTML content of the search result. Only if `include_raw_content` is true.
    - `favicon` string — The favicon URL for the result.
    - `images` object[] — A list of images extracted from this search result. Only included when `include_images` is `true`. If `include_image_descriptions` is `true`, each item will have `url` and `description`.
      - `url` string
      - `description` string
  - `auto_parameters` object — A dictionary of the selected auto_parameters, only shown when `auto_parameters` is true.
  - `response_time` number, float, required — Time in seconds it took to complete the request.
  - `usage` object — Credit usage details for the request.
  - `request_id` string — A unique request identifier you can share with customer support to help resolve issues with specific requests.

## Other responses

- `400` — Bad Request - Your request is invalid.
- `401` — Unauthorized - Your API key is wrong or missing.
- `429` — Too many requests - Rate limit exceeded
- `432` — Key limit or Plan Limit exceeded
- `433` — PayGo limit exceeded
- `500` — Internal Server Error - We had a problem with our server.

---

[API](https://skmtc.net/tavily/apis/tavily-search-and-extract-api.md) · [All operations](https://skmtc.net/tavily/apis/tavily-search-and-extract-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tavily/tavily-search-and-extract-api/revisions/9126e7d2df75/schema)