> ## Documentation Index > Fetch the complete documentation index at: https://dev.writer.com/llms.txt > Use this file to discover all available pages before exploring further. # Search the web **Deprecation notice**: The [web search API endpoint](/api-reference/tool-api/web-search) at `/v1/tools/web-search` is deprecated and will be removed on **December 22, 2025**. **Migration path**: Use the [web search tool](/home/web-search-tool) in chat completions to perform web searches during conversations. The web search tool provides the same search capabilities within a chat completion workflow. See the [migration guide](/api-reference/migration-guides/web-search) for detailed instructions. The Web Search API allows you to search the web for information and get real-time results. This tool is useful for finding current information, news, and facts that may not be available in your model's training data or in your Knowledge Graphs. You need an API key to access the Writer API. Get an API key by following the steps in the [API quickstart](/home/quickstart). We recommend setting the API key as an environment variable in a `.env` file with the name `WRITER_API_KEY`. ## Overview The web search tool enables you to: * Search for current information and news * Find factual information from reliable sources * Get real-time data that may not be in your model's training data * Filter results by domain, time range, and geographic location * Control search depth and result comprehensiveness ## Request example ```bash cURL theme={null} curl --location 'https://api.writer.com/v1/tools/web-search' \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer $WRITER_API_KEY" \ --data '{ "query": "How do I get an API key for the Writer API?", "include_domains": ["dev.writer.com"] }' ``` ```python Python theme={null} from writerai import Writer # Initialize the Writer client. If you don't pass the `api_key` parameter, # the client looks for the `WRITER_API_KEY` environment variable. client = Writer() response = client.tools.web_search( query="How do I get an API key for the Writer API?", include_domains=["dev.writer.com"] ) print(response.answer) ``` ```javascript JavaScript theme={null} import { Writer } from "writer-sdk"; // Initialize the Writer client. If you don't pass the `apiKey` parameter, // the client looks for the `WRITER_API_KEY` environment variable. const client = new Writer(); const response = await client.tools.webSearch({ query: "How do I get an API key for the Writer API?", include_domains: ["dev.writer.com"] }); console.log(response.answer); ``` ### Request parameters | Parameter | Type | Required | Description | | --------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Yes | The search query to execute | | `topic` | string | No | The search topic category. Use `news` for current events and news articles, or `general` for broader web search. Default: `general` | | `search_depth` | string | No | Controls search comprehensiveness. Use `basic` for fewer but highly relevant results, or `advanced` for deeper search with more results. Default: `basic` | | `chunks_per_source` | integer | No | 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 | No | Limits the number of search results returned. Cannot exceed 20 sources | | `time_range` | string | No | Filters results to content published within the specified time range. Options: `day`, `week`, `month`, `year`, `d`, `w`, `m`, `y` | | `days` | integer | No | For news topic searches, specifies how many days of news coverage to include | | `include_raw_content` | string \| Boolean | No | Controls how raw content is included. Options: `text`, `markdown`, `true` (same as markdown), `false` (not included). Default: `false` | | `include_answer` | Boolean | No | Whether to include a generated answer to the query in the response. Default: `true` | | `include_domains` | array | No | Domains to include in the search | | `exclude_domains` | array | No | Domains to exclude from the search | | `country` | string | No | Localizes search results to a specific country. Only applies to general topic searches | | `stream` | Boolean | No | Enables streaming of search results as they become available. Default: `false` | ### Response format The response contains the search query, generated answer if requested, and an array of sources with their URLs and raw content if requested. | Parameter | Type | Description | | ----------------------- | ------ | ----------------------------------------------------------------------------------- | | `query` | string | The search query that was submitted | | `answer` | string | Generated answer based on the search results. `null` if `include_answer` is `false` | | `sources` | array | The search results found | | `sources[].url` | string | URL of the search result | | `sources[].raw_content` | string | Raw content from the source URL. `null` if `include_raw_content` is `false` | ```json theme={null} { "query": "What are the most significant developments in artificial intelligence this year?", "answer": "This year has seen several significant developments...", "sources": [ { "url": "https://www.ibm.com/think/insights/artificial-intelligence-trends", "raw_content": null }, { "url": "https://www.crescendo.ai/news/latest-ai-news-and-updates", "raw_content": null }, { "url": "https://www.sciencedaily.com/news/computers_math/artificial_intelligence/", "raw_content": null }, { "url": "https://news.microsoft.com/source/features/ai/6-ai-trends-youll-see-more-of-in-2025/", "raw_content": null }, { "url": "https://hai.stanford.edu/ai-index/2025-ai-index-report", "raw_content": null } ] } ``` #### Streaming response When streaming is enabled, the response is delivered as [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events). Each event contains a payload with the query, answer, and sources array. The response is delivered as a stream of events, and the client must listen for each event to receive the complete response. Learn more about [streaming responses](/home/streaming). Below is an example of a streaming response: ```json theme={null} data: {"query":"What are the most significant developments in artificial intelligence this year?","answer":"","sources":[]} data: {"query":"What are the most significant developments in artificial intelligence this year?","answer":"Several","sources":[]} data: {"query":"What are the most significant developments in artificial intelligence this year?","answer":" significant","sources":[]} ``` ## Usage examples ### General web search ```bash cURL theme={null} curl --location 'https://api.writer.com/v1/tools/web-search' \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer $WRITER_API_KEY" \ --data '{ "query": "What are the most significant developments in artificial intelligence this year?" }' ``` ```python Python theme={null} from writerai import Writer # Initialize the Writer client. If you don't pass the `api_key` parameter, # the client looks for the `WRITER_API_KEY` environment variable. client = Writer() response = client.tools.web_search( query="What are the most significant developments in artificial intelligence this year?" ) print(response.answer) ``` ```javascript JavaScript theme={null} import { Writer } from "writer-sdk"; // Initialize the Writer client. If you don't pass the `apiKey` parameter, // the client looks for the `WRITER_API_KEY` environment variable. const client = new Writer(); const response = await client.tools.webSearch({ query: "What are the most significant developments in artificial intelligence this year?" }); console.log(response.answer); ``` ### News search with time filtering ```bash cURL theme={null} curl --location 'https://api.writer.com/v1/tools/web-search' \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer $WRITER_API_KEY" \ --data '{ "query": "What are the latest developments in smartphone technology?", "topic": "news", "time_range": "week", "include_raw_content": "markdown", "max_results": 10 }' ``` ```python Python theme={null} from writerai import Writer # Initialize the Writer client. If you don't pass the `api_key` parameter, # the client looks for the `WRITER_API_KEY` environment variable. client = Writer() response = client.tools.web_search( query="What are the latest developments in smartphone technology?", topic="news", time_range="week", include_raw_content="markdown", max_results=10 ) print(response.answer) ``` ```javascript JavaScript theme={null} import { Writer } from "writer-sdk"; // Initialize the Writer client. If you don't pass the `apiKey` parameter, // the client looks for the `WRITER_API_KEY` environment variable. const client = new Writer(); const response = await client.tools.webSearch({ query: "What are the latest developments in smartphone technology?", topic: "news", time_range: "week", include_raw_content: "markdown", max_results: 10 }); ``` ### Domain-specific search ```bash cURL theme={null} curl --location 'https://api.writer.com/v1/tools/web-search' \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer $WRITER_API_KEY" \ --data '{ "query": "What are some good tutorials for learning machine learning?", "include_domains": ["github.com", "stackoverflow.com"], "exclude_domains": ["quora.com"], "search_depth": "advanced", "chunks_per_source": 2 }' ``` ```python Python theme={null} from writerai import Writer # Initialize the Writer client. If you don't pass the `api_key` parameter, # the client looks for the `WRITER_API_KEY` environment variable. client = Writer() response = client.tools.web_search( query="What are some good tutorials for learning machine learning?", include_domains=["github.com", "stackoverflow.com"], exclude_domains=["quora.com"], search_depth="advanced", chunks_per_source=2 ) print(response.answer) ``` ```javascript JavaScript theme={null} import { Writer } from "writer-sdk"; // Initialize the Writer client. If you don't pass the `apiKey` parameter, // the client looks for the `WRITER_API_KEY` environment variable. const client = new Writer(); const response = await client.tools.webSearch({ query: "What are some good tutorials for learning machine learning?", include_domains: ["github.com", "stackoverflow.com"], exclude_domains: ["quora.com"], search_depth: "advanced", chunks_per_source: 2 }); console.log(response.answer); ``` ## Best practices * **Use specific queries**: More specific queries tend to yield better results * **Choose appropriate topic**: Use `news` for current events and `general` for broader searches * **Filter by domains**: Use `include_domains` and `exclude_domains` to focus on reliable sources * **Control search depth**: Use `basic` for quick searches and `advanced` for comprehensive research * **Set time ranges**: Use `time_range` to get current information when needed * **Limit results**: Use `max_results` to control response size and processing time ## Next steps Learn about other tools and capabilities available in the Writer API: * [PDF parsing](/api-reference/tool-api/pdf-parser) * [Web search tool for chat completions](/home/web-search-tool) * [Tool calling](/home/tool-calling) * [Knowledge Graph queries](/home/kg-query)