Search the web

Deprecation notice: The web search API endpoint at /v1/tools/web-search is deprecated and will be removed on December 22, 2025.Migration path: Use the 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 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.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

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"]
    }'

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)

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`

{
  "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). 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. Below is an example of a streaming response:

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

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?"
    }'

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)

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

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

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)

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

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

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)

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:

Getting started

Monitor and manage

Core concepts

Models and pricing

Connect to your data

Chat completions

No-code agents

Knowledge Graphs

Tool calling

Additional capabilities

Integrations

Security and compliance

Resources

Overview

Request example

Request parameters

Response format

Streaming response

Usage examples

General web search

News search with time filtering

Domain-specific search

Best practices

Next steps

​Overview

​Request example

​Request parameters

​Response format

​Streaming response

​Usage examples

​General web search

​News search with time filtering

​Domain-specific search

​Best practices

​Next steps

Overview

Request example

Request parameters

Response format

Streaming response

Usage examples

General web search

News search with time filtering

Domain-specific search

Best practices

Next steps