Web search in a chat

The web search tool for chat completions allows you to search the web for current information during a conversation. This guide explains how to use the web search tool in a chat completion and provides an example of how to use it.

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.

curl --location 'https://api.writer.com/v1/chat' \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $WRITER_API_KEY" \
    --data '{
        "model": "palmyra-x5",
        "messages": [
            {
                "role": "user",
                "content": "What are the latest developments in AI technology?"
            }
        ],
        "tool_choice": "auto",
        "tools": [
            {
                "type": "web_search",
                "function": {
                    "include_domains": ["wikipedia.org", "github.com", "techcrunch.com"],
                    "exclude_domains": ["quora.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()

# Create the tools array containing a web search tool
tools = [{
    "type": "web_search",
    "function": {
        "include_domains": ["wikipedia.org", "github.com", "techcrunch.com"],
        "exclude_domains": ["quora.com"]
    }
}]

# Create the messages array containing a user message that prompts the model to use the web search tool
messages = [{"role": "user", "content": "What are the latest developments in AI technology?"}]

response = client.chat.chat(
    model="palmyra-x5", 
    messages=messages, 
    tools=tools,  # The tools array defined earlier.
    tool_choice="auto"
)

print(response.choices[0].message.content)

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();

// Create the tools array containing a web search tool
tools = [{
    type: "web_search",
    function: {
        include_domains: ["wikipedia.org", "github.com", "techcrunch.com"],
        exclude_domains: ["quora.com"]
    }
}]

// Create the messages array containing a user message that prompts the model to use the web search tool
const messages = [{role: "user", content: "What are the latest developments in AI technology?"}];

const response = await client.chat.chat({
    model: "palmyra-x5", 
    messages: messages, 
    tools: tools, // The tools array defined earlier.
    tool_choice: "auto"
});

console.log(response.choices[0].message.content);

Tool structure

The web search tool allows you to search the web during a chat completion.

To customize search parameters like including raw source text, limiting the number of sources, or specifying time ranges, include these requirements in your prompt to the model. The model uses these parameters when making the web search call. For example, your message to the model might include:

“Include raw source text”
“Limit the number of sources to 5”
“Search for news articles from the last 30 days”

Example:

"messages": [{
  "role": "user",
  "content": "Find the latest news about AI technology. Include raw source text and limit the number of sources to 5."
}]

To use the web search tool, add it to the tools array in your chat-completion endpoint request. The web search tool object has the following structure:

Parameter	Type	Description
`type`	`string`	The type of tool, which is `web_search` for the web search tool
`function`	`object`	An object containing the tool’s configuration
`function.include_domains`	`array`	An array of domains to include in the search results
`function.exclude_domains`	`array`	An array of domains to exclude from the search results

Below shows the structure of the web search tool object.

"tools": [
    {
        "type": "web_search",
        "function": {
            "include_domains": ["wikipedia.org", "github.com"],
            "exclude_domains": ["quora.com"]
        }
    }  
]

tools = [{
    "type": "web_search",
    "function": {
        "include_domains": ["wikipedia.org", "github.com"],
        "exclude_domains": ["quora.com"]
    }
}]

const tools = [{
    type: "web_search",
    function: {
        include_domains: ["wikipedia.org", "github.com"],
        exclude_domains: ["quora.com"]
    }
}]

You can only pass one prebuilt tool in the tools array at a time. However, you can pass multiple custom tools in the same request.Prebuilt tools are:

Response format

For non-streaming responses, the search results and answer are in the choices[0].message.content field. For streaming responses, the search results and answer are in the choices[0].delta.content field. The response also contains a web_search_data field that contains the following information:

Parameter	Type	Description
`query`	`string`	The search query that was submitted
`answer`	`string`	Generated answer based on the search results
`sources`	`array`	The search results found
`sources[].url`	`string`	URL of the search result
`sources[].raw_content`	`string`	Raw content from the source URL (if requested)

You can use the web search tool with streaming chat responses, but the web search tool call is not streamed. The sources comes back in the choices[0].delta.content field once the full search is complete. Then, the response from the model is streamed.If you are unfamiliar with the chat completions endpoint or streaming vs. non-streaming responses, learn more in the chat completion guide.

See the chat completion endpoint for more information on the response fields.

{
  "id": "2ac04514-35cd-49e7-8d11-df0ace4336db",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "finish_reason": "tool_calls",
      "message": {
        "content": "The latest developments in AI technology are happening at a rapid pace...",
        "role": "assistant",
        "tool_calls": null,
        "graph_data": {
          "sources": null,
          "status": null,
          "subqueries": null
        },
        "llm_data": null,
        "image_data": null,
        "translation_data": null,
        "web_search_data": {
          "search_depth": "advanced",
          "sources": [
            {
              "url": "https://en.wikipedia.org/wiki/AI_boom",
              "raw_content": null
            },
            {
              "url": "https://techcrunch.com/2025/05/30/its-not-your-imagination-ai-is-speeding-up-the-pace-of-change/",
              "raw_content": null
            },
            {
              "url": "https://techcrunch.com/category/artificial-intelligence/",
              "raw_content": null
            },
            {
              "url": "https://techcrunch.com/2025/08/03/inside-openais-quest-to-make-ai-do-anything-for-you/",
              "raw_content": null
            },
            {
              "url": "https://en.wikipedia.org/wiki/Artificial_intelligence",
              "raw_content": null
            }
          ]
        },
        "refusal": null
      },
      "logprobs": null,
      "trace_details": null
    }
  ],
  "created": 1754521236,
  "model": "palmyra-x5",
  "usage": {
    "prompt_tokens": 3736,
    "total_tokens": 3764,
    "completion_tokens": 28,
    "completion_tokens_details": null,
    "prompt_token_details": null
  },
  "system_fingerprint": "v1",
  "service_tier": null
}

{
  "id": "94131ba5-35f0-4319-b4a6-3929ebb1669a",
  "choices": [
    {
      "delta": {
        "content": "",
        "graph_data": {
          "sources": null,
          "status": null,
          "subqueries": null
        },
        "llm_data": null,
        "refusal": null,
        "role": "assistant",
        "tool_calls": null,
        "translation_data": null,
        "image_data": null,
        "web_search_data": {
          "search_depth": "advanced",
          "sources": [
            {
              "url": "https://en.wikipedia.org/wiki/AI_boom",
              "raw_content": null
            },
            {
              "url": "https://techcrunch.com/2025/05/12/improvements-in-reasoning-ai-models-may-slow-down-soon-analysis-finds/",
              "raw_content": null
            },
            {
              "url": "https://techcrunch.com/category/artificial-intelligence/",
              "raw_content": null
            },
            {
              "url": "https://en.wikipedia.org/wiki/Progress_in_artificial_intelligence",
              "raw_content": null
            }
          ]
        }
      },
      "finish_reason": null,
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "",
        "refusal": null,
        "role": "assistant",
        "graph_data": {
          "sources": null,
          "status": null,
          "subqueries": null
        },
        "llm_data": null,
        "tool_calls": null,
        "translation_data": null,
        "image_data": null,
        "web_search_data": {
          "search_depth": "advanced",
          "sources": [
            {
              "url": "https://en.wikipedia.org/wiki/AI_boom",
              "raw_content": null
            },
            {
              "url": "https://techcrunch.com/2025/05/12/improvements-in-reasoning-ai-models-may-slow-down-soon-analysis-finds/",
              "raw_content": null
            },
            {
              "url": "https://techcrunch.com/category/artificial-intelligence/",
              "raw_content": null
            },
            {
              "url": "https://en.wikipedia.org/wiki/Progress_in_artificial_intelligence",
              "raw_content": null
            }
          ]
        }
      },
      "trace_details": null
    }
  ],
  "created": 1754521528,
  "model": "palmyra-x5",
  "object": "chat.completion.chunk",
  "service_tier": null,
  "system_fingerprint": "v1",
  "usage": null
}

Usage example

This example uses the web search tool to find current information about AI developments during a chat completion. To use the web search tool:

Create a tools array that specifies the web search tool.

The tool array should include the type and function parameters. The function parameter should include the include_domains and exclude_domains parameters.

Create a messages array that contains the user message that prompts the model to use the web search tool.

The message should contain the requirements for the search, such as including raw source text, limiting the number of sources, or specifying time ranges.

Call the chat.chat method with the tools parameter set to the tools array and tool_choice set to auto.

curl --location 'https://api.writer.com/v1/chat' \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $WRITER_API_KEY" \
    --data '{
        "model": "palmyra-x5",
        "messages": [
            {
                "role": "user",
                "content": "What are the latest developments in AI technology?"
            }
        ],
        "tool_choice": "auto",
        "tools": [
            {
                "type": "web_search",
                "function": {
                    "include_domains": ["wikipedia.org", "github.com", "techcrunch.com"],
                    "exclude_domains": ["quora.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()

messages = [{"role": "user", "content": "What are the latest developments in AI technology?"}]

response = client.chat.chat(
    model="palmyra-x5", 
    messages=messages, 
    tools=tools,  # The tools array defined earlier.
    tool_choice="auto"
)

print(response.choices[0].message.content)

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 messages = [{role: "user", content: "What are the latest developments in AI technology?"}];

const response = await client.chat.chat({
    model: "palmyra-x5", 
    messages: messages, 
    tools: tools, // The tools array defined earlier.
    tool_choice: "auto"
});

console.log(response.choices[0].message.content);

If you want to verify the web search data in the response, you can print the web_search_data field to see the search query, answer, and sources that the web search tool used.

print(response.choices[0].message.web_search_data)

console.log(response.choices[0].message.web_search_data);

By following this guide, you can use the web search tool to have the model search the web for current information during a chat completion.

Next steps

Learn more about the prebuilt tools available for chat completions:

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

Tool structure

Response format

Usage example

Next steps

​Tool structure

​Response format

​Usage example

​Next steps

Tool structure

Response format

Usage example

Next steps