Anthropic Proxy

The MetrixLLM gateway provides a drop-in proxy for Anthropic’s Messages API. Use your existing Anthropic SDKs or raw HTTP requests by changing only the Base URL and API key.

Base URL

https://gateway.metrixllm.com

Authentication

All requests require a MetrixLLM API key. The gateway accepts both formats:

x-api-key: sk-metrix-YOUR_API_KEY

Authorization: Bearer sk-metrix-YOUR_API_KEY

Do not use your Anthropic API key. The gateway authenticates requests using MetrixLLM keys (sk-metrix-* prefix). The gateway then uses its own provider keys (or your BYOK keys) to call Anthropic.

Internal Authentication

For backend-to-gateway communication, the gateway supports internal authentication:

Header	Required	Description
`x-metrix-internal`	Yes	Shared secret matching `HEALTH_CHECK_SECRET` (timing-safe comparison)
`x-metrix-workspace-id`	Yes*	Workspace UUID (use `x-workspace-id` as fallback)

Internal auth skips the standard API key validation. Used by the MetrixLLM backend for playground, replay, and batch operations.

Endpoints

Method	Path	Description
`POST`	`/anthropic/v1/messages`	Messages (returns Anthropic-native format)

Request Headers

Every request supports these headers:

Header	Type	Required	Description
`x-api-key`	`string`	Yes*	`sk-metrix-{key}` — MetrixLLM API key
`Authorization`	`string`	Yes*	`Bearer sk-metrix-{key}` — alternative to `x-api-key`
`Content-Type`	`string`	Yes	Must be `application/json`
`anthropic-version`	`string`	No	Anthropic API version (e.g. `2023-06-01`). Forwarded to upstream.

Session Tracing Use these headers to group related requests into sessions and trace spans:

Header	Description	Stored In
`metrix-session-id`	Unique session identifier — groups related requests into a traceable session	`workspace_logs.session_id`
`metrix-parent-id`	Links a request to a parent span in the session trace	`workspace_logs.parent_id`
`metrix-session-name`	Human-readable name for the span (for dashboard display)	`workspace_logs.span_name`

Custom Properties Attach up to 10 custom metadata properties per request:

Header Pattern	Description
`metrix-property-{key}`	Custom metadata property. Used for rate limit targeting, analytics, and filtering.

Example: metrix-property-team: engineering, metrix-property-environment: production Worker-to-Gateway These headers are set by the Cloudflare Edge Worker when routing through the Durable Object balance system:

Header	Description
`x-balance`	Workspace credit balance from Durable Object
`x-internal-signature`	HMAC-SHA256 signature of `{workspace_id}:{balance}` verified with `DO_SYNC_SECRET`

IP Detection

Header	Description
`x-forwarded-for`	Client IP address (first IP in comma-separated list). Trusted only when peer is a private/local address.
`x-real-ip`	Fallback client IP header. Same trust rules as `x-forwarded-for`.
`cf-ipcountry`	Cloudflare-specific country code of the connecting client (e.g. `US`, `IN`). Used for request logging and analytics.

Messages

Request Body

Send standard Anthropic Messages API requests. The gateway accepts all standard Anthropic fields plus MetrixLLM-specific extensions.

Field	Type	Required	Description
`model`	`string`	Yes	Model identifier (e.g. `claude-opus-4-20250514`, `claude-sonnet-4-20250514`)
`messages`	`array`	Yes	Array of message objects
`max_tokens`	`integer`	Yes	Maximum output tokens (Anthropic requires this; defaults to 8192 if not provided)
`system`	`string \| array`	No	System prompt (top-level field, not a message)
`temperature`	`number`	No	Sampling temperature (0-1)
`top_p`	`number`	No	Nucleus sampling parameter
`stop_sequences`	`array`	No	Stop sequences
`stream`	`boolean`	No	Enable streaming
`tools`	`array`	No	Tool definitions (Anthropic format)
`tool_choice`	`object`	No	Tool selection strategy
`thinking`	`object`	No	Extended thinking configuration (see Thinking)
`mode`	`string`	No	Key selection: `"auto"` (default), `"byok"`, or `"native"`
`web_search`	`boolean \| string`	No	Enable web search: `true` (standard), `"native"` (Anthropic built-in)
`web_search_max_uses`	`integer`	No	Max web search queries per request (native mode)
`prompt_id`	`string`	No	Use a stored prompt template
`inputs`	`object`	No	Template variables for prompt placeholders

Message Format

Messages follow the standard Anthropic format with content blocks:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "What is in this image?"},
    {"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": "..."}}
  ]
}

Examples

curl -X POST https://gateway.metrixllm.com/anthropic/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-metrix-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "metrix-session-id: session_abc123" \
  -H "metrix-session-name: Document Analysis" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

import anthropic

client = anthropic.Anthropic(
    base_url="https://gateway.metrixllm.com/anthropic",
    api_key="sk-metrix-YOUR_API_KEY",
)

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful assistant.",
    messages=[
        {"role": "user", "content": "What is the capital of France?"},
    ],
)

print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://gateway.metrixllm.com/anthropic",
  apiKey: "sk-metrix-YOUR_API_KEY",
});

const message = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  system: "You are a helpful assistant.",
  messages: [
    { role: "user", content: "What is the capital of France?" },
  ],
});

console.log(message.content[0].text);

Response Body

{
  "id": "msg_aK3x9mP2",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-20250514",
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 25,
    "output_tokens": 8
  }
}

Response Headers

Every successful response includes these headers:

Header	Description
`Content-Type`	Always `application/json`
`X-Metrix-Provider`	Resolved upstream provider (e.g. `anthropic`, `openai`)
`X-Metrix-Model`	Actual model used for the request
`X-Metrix-Cache-Status`	`"HIT"` or `"miss"` (semantic cache)
`X-Metrix-Retry-Count`	Number of retry attempts (0 if none)
`X-Metrix-Retry-Status`	`"success"`, `"failed"`, or `"not_triggered"`
`X-Metrix-Fallback`	`"true"` if a fallback provider was used (only present when applicable)
`X-RateLimit-Limit`	Configured limit for the rate window
`X-RateLimit-Remaining`	Remaining quota in the current window
`X-RateLimit-Requests-Remaining`	Remaining requests in the current rate window
`X-RateLimit-Tokens-Remaining`	Remaining tokens in the current rate window

On cache HIT responses, only Content-Type and X-Metrix-Cache-Status: HIT are returned. On rate limited responses (429 Too Many Requests):

Header	Description
`Retry-After`	Seconds to wait before retrying
`X-RateLimit-{type}-Limit`	Maximum limit (e.g. `X-RateLimit-rpm-Limit`, `X-RateLimit-tpm-Limit`)
`X-RateLimit-{type}-Remaining`	Remaining count in the current window
`X-RateLimit-Reset`	Seconds until the rate window resets

Streaming

Set "stream": true to receive Server-Sent Events (SSE) in Anthropic’s streaming format.

curl -X POST https://gateway.metrixllm.com/anthropic/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-metrix-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Write a haiku about coding."}
    ],
    "stream": true
  }'

import anthropic

client = anthropic.Anthropic(
    base_url="https://gateway.metrixllm.com/anthropic",
    api_key="sk-metrix-YOUR_API_KEY",
)

with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a haiku about coding."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://gateway.metrixllm.com/anthropic",
  apiKey: "sk-metrix-YOUR_API_KEY",
});

const stream = client.messages.stream({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Write a haiku about coding." }],
});

for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

Thinking (Extended Thinking)

Enable extended thinking for deeper reasoning. The gateway converts between Anthropic’s thinking format and other provider formats automatically.

{
  "model": "claude-opus-4-20250514",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  },
  "messages": [
    {"role": "user", "content": "Explain quantum entanglement in detail."}
  ]
}

Field	Type	Description
`thinking.type`	`string`	Must be `"enabled"` to activate thinking
`thinking.budget_tokens`	`integer`	Maximum tokens allocated to thinking (higher = deeper reasoning)

When using the gateway’s generic proxy (/v1/chat/completions), you can use a simplified thinking field: "low" (1000 tokens), "medium" (5000 tokens), or "high" (10000 tokens). The gateway converts these to the appropriate provider-specific format.

Tool Use

Define tools using Anthropic’s native format. The gateway automatically converts between tool formats when routing to different providers.

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name"
          }
        },
        "required": ["location"]
      }
    }
  ],
  "messages": [
    {"role": "user", "content": "What is the weather in San Francisco?"}
  ]
}

Tool Choice

Control tool selection with tool_choice:

Value	Behavior
`{"type": "auto"}`	Model decides whether to use a tool
`{"type": "any"}`	Model must use one of the provided tools
`{"type": "none"}`	Model must not use any tools
`{"type": "tool", "name": "get_weather"}`	Model must use the specified tool

Web Search

Enable web search to give the model access to real-time information.

Value	Behavior
`true`	Performs a web search and injects results into the system prompt
`"native"`	Uses Anthropic’s built-in `web_search_20250305` server tool
`false` or absent	No web search

Additional parameters:

Field	Type	Default	Description
`web_search_max_uses`	`integer`	Provider default	Maximum number of search queries per request

Native Web Search Example

curl -X POST https://gateway.metrixllm.com/anthropic/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-metrix-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What are the latest developments in AI?"}
    ],
    "tools": [
      {"type": "web_search_20250305", "name": "web_search", "max_uses": 5}
    ]
  }'

import anthropic

client = anthropic.Anthropic(
    base_url="https://gateway.metrixllm.com/anthropic",
    api_key="sk-metrix-YOUR_API_KEY",
)

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What are the latest developments in AI?"}],
    tools=[
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 5}
    ],
)

print(message.content)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://gateway.metrixllm.com/anthropic",
  apiKey: "sk-metrix-YOUR_API_KEY",
});

const message = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What are the latest developments in AI?" }],
  tools: [
    { type: "web_search_20250305", name: "web_search", max_uses: 5 },
  ],
});

console.log(message.content);

Prompt Management

Use prompt_id to reference a stored prompt template. The gateway fetches the template, renders {{variable}} placeholders with values from inputs, and sends the rendered messages to the provider.

{
  "model": "claude-sonnet-4-20250514",
  "prompt_id": "prompt_abc123",
  "inputs": {
    "user_name": "Alice",
    "topic": "quantum computing"
  }
}

Error Responses

Errors return a JSON body following Anthropic’s error format. The HTTP status code indicates the error type.

Status	Meaning
`400`	Invalid request (missing model, malformed body)
`401`	Invalid or missing API key
`402`	Insufficient credits
`403`	Workspace disabled, IP not allowed, or model not enabled
`404`	Model not recognized
`429`	Rate limit exceeded
`446`	Guardrail block (request blocked by content policy)
`500`	Internal gateway error
`502`	Upstream provider error
`503`	Provider circuit breaker open

Error Response Format

{
  "error": {
    "message": "Model 'claude-5' is not recognized.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Retry and Fallback

The gateway automatically retries failed requests and falls back to alternative providers:

Retry: Retries on 429, 500, 502, 503, 504 status codes with exponential backoff
Fallback: If the primary provider fails, the gateway tries the next configured provider in the chain
Circuit Breaker: Providers with repeated failures are temporarily skipped (circuit opens for 60 seconds)
Cerebras Fallback: If all configured providers fail on system errors, the gateway falls back to Cerebras (if enabled)

These features are transparent to your application — you receive a single successful response.

Mode Override

Control provider key selection with the mode field:

Value	Behavior
`"auto"`	Default. Uses your BYOK key if configured, otherwise uses MetrixLLM native key.
`"byok"`	Forces use of your own API key. Fails if no key is configured for the provider.
`"native"`	Forces use of MetrixLLM’s managed key. Skips BYOK keys entirely.

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Hello!"}],
  "mode": "native"
}

Overview

Connect

Build

Observe

Optimize

Manage

Gateway API Reference

Base URL

Authentication

Internal Authentication

Endpoints

Request Headers

Messages

Request Body

Message Format

Examples

Response Body

Response Headers

Streaming

Thinking (Extended Thinking)

Tool Use

Tool Choice

Web Search

Native Web Search Example

Prompt Management

Error Responses

Error Response Format

Retry and Fallback

Mode Override

​Base URL

​Authentication

​Internal Authentication

​Endpoints

​Request Headers

​Messages

​Request Body

​Message Format

​Examples

​Response Body

​Response Headers

​Streaming

​Thinking (Extended Thinking)

​Tool Use

​Tool Choice

​Web Search

​Native Web Search Example

​Prompt Management

​Error Responses

​Error Response Format

​Retry and Fallback

​Mode Override

Base URL

Authentication

Internal Authentication

Endpoints

Request Headers

Messages

Request Body

Message Format

Examples

Response Body

Response Headers

Streaming

Thinking (Extended Thinking)

Tool Use

Tool Choice

Web Search

Native Web Search Example

Prompt Management

Error Responses

Error Response Format

Retry and Fallback

Mode Override