Anthropic Integration

Integrate Helicone with Anthropic Claude models

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:

Python

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

Python

pip install anthropic

Node.js

npm install @anthropic-ai/sdk

Configuration

Basic Setup

Only two changes are needed:

1. Change base URL to https://anthropic.helicone.ai
2. Add Helicone-Auth header with your API key

Environment Variables

Set up your environment:

.env

ANTHROPIC_API_KEY=sk-ant-...
HELICONE_API_KEY=sk-helicone-...

Features

Streaming Support

Helicone fully supports streaming responses:

Python

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

Tool Use

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:

Python

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": "[e-mail]",
        "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:

1. Verify your HELICONE_API_KEY is correct
2. Ensure base URL is https://anthropic.helicone.ai (no /v1)
3. Check that Helicone-Auth header includes Bearer prefix
4. Verify anthropic-version header is set (required by Anthropic)
5. Wait 10-30 seconds for requests to appear

Still not working? Check the response for error details.

anthropic-version header missing

Anthropic requires the anthropic-version header. Add it to your requests:

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')}",
        "anthropic-version": "2023-06-01",
    },
)

The SDK usually handles this automatically.

Rate limiting issues

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:

• Basic Anthropic integration
• Streaming with prompt caching

Next Steps

Custom Properties

Add metadata to your requests

Sessions

Track multi-turn conversations

Prompt Caching

Monitor cache performance

Dashboard

Explore your analytics