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
    }
  }
}
I