Skip to main content
The web search tool for chat completions allows you to search the web for current information during a conversation with a Palmyra model. While Palmyra models have extensive knowledge, they may not have access to the most current information or real-time data. The web search tool enables your AI assistant to find up-to-date information, news, and facts from the web to provide more accurate and timely responses. The Writer API also has a web-search endpoint that you can use to search the web outside of a chat completion. See the web search API guide for more information. 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.

​
Tool structure

The web search tool allows you to search the web during a chat with a Palmyra model. 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
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”
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.

​
Create a tools array containing a web search tool

First, create a tools array that specifies the web search tool you want to use. 
"tools": [
    {
        "type": "web_search",
        "function": {
            "include_domains": ["wikipedia.org", "github.com", "techcrunch.com"],
            "exclude_domains": ["quora.com"]
        }
    }
]

​
Send the request using chat completions

Add the tools array to the chat endpoint call along with your array of messages. Setting tool_choice to auto allows the model to choose when to use the web search tool, based on the message provided in the messages array. The response contains the search results and generated answer in the choices[0].message.content field. 
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: