---
title: "Web search"
method: POST
path: "/v1/tools/web-search"
tags: ["Tools API"]
---

# Web search

`POST /v1/tools/web-search`

Search the web for information about a given query and return relevant results with source URLs.

## Request body

- WebSearchRequest
  - `query` string — The search query.
  - `topic` 'general' | 'news' — The search topic category. Use `news` for current events and news articles, or `general` for broader web search.
  - `search_depth` 'basic' | 'advanced' — Controls search comprehensiveness: - `basic`: Returns fewer but highly relevant results - `advanced`: Performs a deeper search with more results
  - `chunks_per_source` integer — Only applies when `search_depth` is `advanced`. Specifies how many text segments to extract from each source. Limited to 3 chunks maximum.
  - `max_results` integer — Limits the number of search results returned. Cannot exceed 20 sources.
  - `time_range` 'day' | 'week' | 'month' | 'year' | 'd' | 'w' | 'm' | 'y' — Filters results to content published within the specified time range back from the current date. For example, `week` or `w` returns results from the past 7 days.
  - `days` integer — For news topic searches, specifies how many days of news coverage to include.
  - `include_raw_content` union — Controls how raw content is included in search results: - `text`: Returns plain text without formatting markup - `markdown`: Returns structured content with markdown formatting (headers, links, bold text) - `true`: Same as `markdown` - `false`: Raw content is not included (default if unset)
    - 'text' | 'markdown'
    - boolean
  - `include_answer` boolean — Whether to include a generated answer to the query in the response. If `false`, only search results are returned.
  - `include_domains` string[] — Domains to include in the search. If unset, the search includes all domains.
  - `exclude_domains` string[] — Domains to exclude from the search. If unset, the search includes all 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' — Localizes search results to a specific country. Only applies to general topic searches.
  - `stream` boolean — Enables streaming of search results as they become available.

## Response `200`

Successful response

- WebSearchResponse
  - `query` string, required — The search query that was submitted.
  - `answer` string — Generated answer based on the search results. Not included if `include_answer` is `false`.
  - `sources` object[], required — The search results found.
    - `url` string — URL of the search result.
    - `raw_content` string — Raw content from the source URL. Not included if `include_raw_content` is `false`.

## Changes

- **2025-08-12** `0bbaae2a6920` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/writer/apis/api/changes/v1/tools/web-search/post.md)

---

[API](https://skmtc.dev/writer/apis/api.md) · [All operations](https://skmtc.dev/writer/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/writer/api/revisions/ae230e1d8c09/schema)