Integrate Helicone with Anthropic to track and monitor your Claude model usage with complete observability.
Quick Start Integrate Helicone with Anthropic by changing your base URL and adding your API key:
import os from anthropic import Anthropic client = Anthropic( api_key = os.getenv( "ANTHROPIC_API_KEY" ), base_url = "https://anthropic.helicone.ai" , default_headers = { "Helicone-Auth" : f "Bearer { os.getenv( 'HELICONE_API_KEY' ) } " , }, ) # Use the client normally response = client.messages.create( model = "claude-sonnet-4-20250514" , max_tokens = 1024 , messages = [ { "role" : "user" , "content" : "What is the capital of France?" } ], ) print (response.content[ 0 ].text)
Installation npm install @anthropic-ai/sdk
Configuration Basic Setup Only two changes are needed:
Change base URL to https://anthropic.helicone.aiAdd Helicone-Auth header with your API key
Environment Variables Set up your environment:
ANTHROPIC_API_KEY = sk-ant-... HELICONE_API_KEY = sk-helicone-...
Features Streaming Support Helicone fully supports streaming responses:
with client.messages.stream( model = "claude-sonnet-4-20250514" , max_tokens = 1024 , messages = [{ "role" : "user" , "content" : "Write a story" }], ) as stream: for text in stream.text_stream: print (text, end = "" , flush = True )
Prompt Caching Helicone automatically tracks Anthropic’s prompt caching:
system = [ { "type" : "text" , "text" : "You are a helpful assistant." * 1000 , "cache_control" : { "type" : "ephemeral" }, } ] response = client.messages.create( model = "claude-sonnet-4-20250514" , max_tokens = 1024 , system = system, messages = [{ "role" : "user" , "content" : "Hello" }], ) # Helicone tracks cache hits and savings automatically
Helicone dashboard shows cache write tokens, cache read tokens, and cost savings from Anthropic’s prompt caching.
Vision Models Log image inputs with Claude:
response = client.messages.create( model = "claude-3-opus-20240229" , max_tokens = 1024 , messages = [ { "role" : "user" , "content" : [ { "type" : "text" , "text" : "What's in this image?" }, { "type" : "image" , "source" : { "type" : "url" , "url" : "https://example.com/image.jpg" , }, }, ], } ], ) # Helicone tracks image assets automatically
Track Claude’s tool usage:
tools = [ { "name" : "get_weather" , "description" : "Get the current weather in a location" , "input_schema" : { "type" : "object" , "properties" : { "location" : { "type" : "string" , "description" : "The city and state, e.g. San Francisco, CA" , } }, "required" : [ "location" ], }, } ] response = client.messages.create( model = "claude-sonnet-4-20250514" , max_tokens = 1024 , tools = tools, messages = [{ "role" : "user" , "content" : "What's the weather in Paris?" }], ) # Helicone automatically logs tool calls
Custom Properties Add metadata to your requests:
response = client.messages.create( model = "claude-sonnet-4-20250514" , max_tokens = 1024 , messages = [{ "role" : "user" , "content" : "Hello" }], extra_headers = { "Helicone-Property-Session" : "session-123" , "Helicone-Property-User" : "user@example.com" , "Helicone-Property-Environment" : "production" , }, )
Learn more about custom properties → Advanced Usage User Tracking Track requests by user:
response = client.messages.create( model = "claude-sonnet-4-20250514" , max_tokens = 1024 , messages = [{ "role" : "user" , "content" : "Hello" }], extra_headers = { "Helicone-User-Id" : "user-123" , }, )
Session Tracking Group related requests into sessions:
response = client.messages.create( model = "claude-sonnet-4-20250514" , max_tokens = 1024 , messages = [{ "role" : "user" , "content" : "Hello" }], extra_headers = { "Helicone-Session-Id" : "session-abc" , "Helicone-Session-Name" : "Customer Support Chat" , "Helicone-Session-Path" : "/chat/support" , }, )
Prompt Tracking Track prompt versions:
response = client.messages.create( model = "claude-sonnet-4-20250514" , max_tokens = 1024 , messages = [{ "role" : "user" , "content" : "Hello" }], extra_headers = { "Helicone-Prompt-Id" : "prompt-v2" , }, )
AWS Bedrock Use Claude via AWS Bedrock with Helicone:
import boto3 from anthropic import AnthropicBedrock client = AnthropicBedrock( aws_access_key = os.getenv( "AWS_ACCESS_KEY_ID" ), aws_secret_key = os.getenv( "AWS_SECRET_ACCESS_KEY" ), aws_region = os.getenv( "AWS_REGION" ), base_url = f "https://bedrock.helicone.ai/v1/ { os.getenv( 'AWS_REGION' ) } " , default_headers = { "Helicone-Auth" : f "Bearer { os.getenv( 'HELICONE_API_KEY' ) } " , }, )
Troubleshooting
Requests not appearing in dashboard
Check these common issues:
Verify your HELICONE_API_KEY is correct
Ensure base URL is https://anthropic.helicone.ai (no /v1)
Check that Helicone-Auth header includes Bearer prefix
Verify anthropic-version header is set (required by Anthropic)
Wait 10-30 seconds for requests to appear
Still not working? Check the response for error details.
anthropic-version header missing
Helicone does not add rate limits. If you’re hitting rate limits, they’re from Anthropic. The error message will be passed through.
Examples from Source See real integration examples in the repository:
Next Steps
Custom Properties Add metadata to your requests
Sessions Track multi-turn conversations
Prompt Caching Monitor cache performance
Dashboard Explore your analytics