Skip to main content
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"]
                }
            }
        ]
    }'

​
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:
ParameterTypeDescription
typestringThe type of tool, which is web_search for the web search tool
functionobjectAn object containing the tool’s configuration
function.include_domainsarrayAn array of domains to include in the search results
function.exclude_domainsarrayAn 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"]
        }
    }  
]
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:
ParameterTypeDescription
querystringThe search query that was submitted
answerstringGenerated answer based on the search results
sourcesarrayThe search results found
sources[].urlstringURL of the search result
sources[].raw_contentstringRaw 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
}

​
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:
  1. 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.
  1. 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.
  1. 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"]
                }
            }
        ]
    }'
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)
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: