Skip to main content

​
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:
  1. Enables the web search tool for the request
  2. Routes the request to Anthropic with the appropriate web search configuration
  3. Returns the response with citations formatted as annotations

​
Quick Start

  • Python
  • Node.js
  • cURL
import openai

client = 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 available
if 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']}")

​
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

ParameterTypeDescription
max_usesintegerMaximum number of web searches allowed per request (default: unlimited)
allowed_domainsarrayRestrict searches to specific domains
blocked_domainsarrayExclude specific domains from search results
user_locationobjectProvide 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
    }
  }
}