Web Search Overview#

Helicone Gateway supports web search for Anthropic models, allowing Claude to search the internet and provide up-to-date information with citations. This feature is enabled by appending :online to the model name, following the same pattern as OpenRouter.

How it Works#

When you append :online to an Anthropic model name (e.g., claude-3-5-sonnet-20241022:online), Helicone automatically:

Enables the web search tool for the request
Routes the request to Anthropic with the appropriate web search configuration
Returns the response with citations formatted as annotations

Quick Start#

import openaiclient = openai.OpenAI(    api_key="YOUR_ANTHROPIC_API_KEY",    base_url="https://gateway.helicone.ai/v1",    default_headers={        "Helicone-Auth": "Bearer YOUR_HELICONE_API_KEY",        "Helicone-Target-Url": "https://api.anthropic.com",    })response = client.chat.completions.create(    model="claude-3-5-sonnet-20241022:online",  # Note the :online suffix    messages=[        {"role": "user", "content": "What are the latest developments in AI?"}    ])# Access citations if availableif response.choices[0].message.annotations:    for annotation in response.choices[0].message.annotations:        print(f"Source: {annotation['url_citation']['title']}")        print(f"URL: {annotation['url_citation']['url']}")

import OpenAI from 'openai';const openai = new OpenAI({  apiKey: 'YOUR_ANTHROPIC_API_KEY',  baseURL: 'https://gateway.helicone.ai/v1',  defaultHeaders: {    'Helicone-Auth': 'Bearer YOUR_HELICONE_API_KEY',    'Helicone-Target-Url': 'https://api.anthropic.com',  }});const response = await openai.chat.completions.create({  model: 'claude-3-5-sonnet-20241022:online',  // Note the :online suffix  messages: [    { role: 'user', content: 'What are the latest developments in AI?' }  ]});// Access citations if availableif (response.choices[0].message.annotations) {  response.choices[0].message.annotations.forEach(annotation => {    console.log(`Source: ${annotation.url_citation.title}`);    console.log(`URL: ${annotation.url_citation.url}`);  });}

curl https://gateway.helicone.ai/v1/chat/completions \  -H "Content-Type: application/json" \  -H "Authorization: Bearer YOUR_ANTHROPIC_API_KEY" \  -H "Helicone-Auth: Bearer YOUR_HELICONE_API_KEY" \  -H "Helicone-Target-Url: https://api.anthropic.com" \  -d '{    "model": "claude-3-5-sonnet-20241022:online",    "messages": [      {        "role": "user",        "content": "What are the latest developments in AI?"      }    ]  }'

Advanced Configuration#

You can customize the web search behavior by including a plugins parameter in your request body:

{  "model": "claude-3-5-sonnet-20241022:online",  "messages": [...],  "plugins": [    {      "id": "web",      "max_uses": 5,      "allowed_domains": ["wikipedia.org", "arxiv.org"],      "blocked_domains": ["example.com"],      "user_location": {        "type": "approximate",        "country": "US"      }    }  ]}

Plugin Options#

Parameter	Type	Description
`max_uses`	integer	Maximum number of web searches allowed per request (default: unlimited)
`allowed_domains`	array	Restrict searches to specific domains
`blocked_domains`	array	Exclude specific domains from search results
`user_location`	object	Provide approximate user location for localized results

Response Format#

When web search is used, the response includes annotations with citation information:

{  "choices": [    {      "message": {        "role": "assistant",        "content": "Based on recent developments, AI has made significant progress in...",        "annotations": [          {            "type": "url_citation",            "url_citation": {              "url": "https://example.com/article",              "title": "Recent AI Breakthroughs",              "content": "The source text that was cited...",              "start_index": 0,              "end_index": 67            }          }        ]      }    }  ]}

Understanding Annotations#

url: The source URL of the cited information
title: The title of the source page
content: The relevant excerpt from the source
start_index: Character position where the citation begins in the response
end_index: Character position where the citation ends in the response

Pricing#

Web search requests are billed at standard Anthropic rates plus any additional costs for web search usage. The usage statistics include:

{  "usage": {    "input_tokens": 1000,    "output_tokens": 500,    "server_tool_use": {      "web_search_requests": 1    }  }}