> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrixllm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Anthropic Drop-in

> Route Anthropic requests through MetrixLLM with a one-line base URL change.

## Base URL

```text theme={null}
https://gateway.metrixllm.com/anthropic
```

## Quick setup

<CodeGroup>
  ```python Python theme={null}
  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": "Hello!"}]
  )
  print(message.content[0].text)
  ```

  ```typescript Node.js theme={null}
  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: "Hello!" }]
  });
  console.log(message.content[0].text);
  ```

  ```bash cURL theme={null}
  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": "Hello!"}]
    }'
  ```
</CodeGroup>

<Warning>
  Do **not** use your Anthropic API key. The gateway authenticates with MetrixLLM keys (`sk-metrix-*` prefix), then uses its own provider keys (or your BYOK keys) to call Anthropic.
</Warning>

## Request Headers

Every request supports these headers for authentication, tracing, and metadata:

| 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**

| 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`

**IP Detection**

| Header            | Description                                          |
| ----------------- | ---------------------------------------------------- |
| `x-forwarded-for` | Client IP address (first IP in comma-separated list) |
| `x-real-ip`       | Fallback client IP header                            |
| `cf-ipcountry`    | Cloudflare country code of the connecting client     |

## Supported models

| Model            | ID                          |
| ---------------- | --------------------------- |
| Claude Sonnet 4  | `claude-sonnet-4-20250514`  |
| Claude 3.5 Haiku | `claude-3-5-haiku-20241022` |

## Routing mode

Control how the gateway authenticates with Anthropic using the `mode` parameter:

| Mode               | Behavior                                                               | Balance deduction                     |
| ------------------ | ---------------------------------------------------------------------- | ------------------------------------- |
| `"auto"` (default) | Uses your BYOK key if configured, otherwise falls back to platform key | BYOK: none. Native: yes               |
| `"byok"`           | Forces your own Anthropic API key (from workspace settings)            | None — your key, your cost            |
| `"native"`         | Forces MetrixLLM's platform key                                        | Yes — deducted from workspace credits |

<CodeGroup>
  ```python Python theme={null}
  # Use your own Anthropic key (BYOK) — never deducts workspace credits
  message = client.messages.create(
      model="claude-sonnet-4-20250514",
      max_tokens=1024,
      mode="byok",
      messages=[{"role": "user", "content": "Hello!"}]
  )
  ```

  ```typescript Node.js theme={null}
  const message = await client.messages.create({
      model: "claude-sonnet-4-20250514",
      max_tokens: 1024,
      mode: "byok",
      messages: [{ role: "user", content: "Hello!" }]
  });
  ```

  ```bash cURL theme={null}
  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,
      "mode": "byok",
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  ```
</CodeGroup>

<Note>
  When `mode` is omitted (or `"auto"`), the gateway prefers your BYOK key if one is configured. If your workspace has insufficient credits and you have a BYOK key, the gateway automatically uses it instead of failing with a payment error.
</Note>

## Web search

### Web search mode (default)

Add `"web_search": true` to your request. The gateway performs a web search, generates optimized search queries, and injects the results into your system prompt.

<CodeGroup>
  ```python Python theme={null}
  message = client.messages.create(
      model="claude-sonnet-4-20250514",
      max_tokens=1024,
      web_search=True,
      messages=[{"role": "user", "content": "What happened in the news today?"}]
  )
  ```

  ```typescript Node.js theme={null}
  const message = await client.messages.create({
      model: "claude-sonnet-4-20250514",
      max_tokens: 1024,
      web_search: true,
      messages: [{ role: "user", content: "What happened in the news today?" }]
  });
  ```

  ```bash cURL theme={null}
  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,
      "web_search": true,
      "messages": [{"role": "user", "content": "What happened in the news today?"}]
    }'
  ```
</CodeGroup>

**Parameters:**

| Parameter            | Type      | Default    | Description                                                                                      |
| -------------------- | --------- | ---------- | ------------------------------------------------------------------------------------------------ |
| `web_search`         | `boolean` | `false`    | Set to `true` to enable web search                                                               |
| `web_search_level`   | `string`  | `"medium"` | `"low"` (1 query, 3 results), `"medium"` (2 queries, 5 results), `"high"` (3 queries, 8 results) |
| `web_search_lang`    | `string`  | `"en"`     | Search language (ISO code)                                                                       |
| `web_search_country` | `string`  | `"us"`     | Search country (ISO code)                                                                        |

### Native mode

Set `"web_search": "native"` to use Anthropic's built-in web search. The gateway adds the `web_search_20250305` tool to your request.

<CodeGroup>
  ```python Python theme={null}
  message = client.messages.create(
      model="claude-sonnet-4-20250514",
      max_tokens=1024,
      web_search="native",
      web_search_max_uses=5,
      messages=[{"role": "user", "content": "What's the latest AI news?"}]
  )
  ```

  ```typescript Node.js theme={null}
  const message = await client.messages.create({
      model: "claude-sonnet-4-20250514",
      max_tokens: 1024,
      web_search: "native",
      web_search_max_uses: 5,
      messages: [{ role: "user", content: "What's the latest AI news?" }]
  });
  ```

  ```bash cURL theme={null}
  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,
      "web_search": "native",
      "web_search_max_uses": 5,
      "messages": [{"role": "user", "content": "What'\''s the latest AI news?"}]
    }'
  ```
</CodeGroup>

**Native-specific parameters:**

| Parameter             | Type      | Description                                         |
| --------------------- | --------- | --------------------------------------------------- |
| `web_search_max_uses` | `integer` | Maximum number of search queries Anthropic can make |

<Note>
  In native mode, Anthropic handles search internally using its own `web_search_20250305` tool. The gateway adds this tool to your tools array automatically — you don't need to define it yourself.
</Note>

## Extended thinking

Claude supports extended thinking for complex reasoning tasks:

```python theme={null}
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "Solve this step by step: what is 2^10 + 3^5?"}]
)
```

## Tool use

```python theme={null}
tools = [
    {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "City name"}
            },
            "required": ["location"]
        }
    }
]

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "What's the weather in London?"}]
)
```

## Streaming

```python theme={null}
with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="")
```

## Prompt management

Reference a stored prompt template by ID:

```python theme={null}
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    prompt_id="your-prompt-uuid",
    inputs={"user_name": "Alice"},
    messages=[{"role": "user", "content": "Hello!"}]
)
```

## Custom properties

Attach metadata for analytics and rate limit targeting:

```python theme={null}
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={
        "metrix-property-team": "backend",
        "metrix-property-env": "production",
        "metrix-session-id": "session_abc123"
    }
)
```

## Response headers

Every response includes these headers:

| Header                           | Description                                                             |
| -------------------------------- | ----------------------------------------------------------------------- |
| `Content-Type`                   | Always `application/json`                                               |
| `X-Metrix-Provider`              | Provider that served the request (e.g. `anthropic`, `openai`, `google`) |
| `X-Metrix-Model`                 | Exact 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 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 current window                                    |
| `X-RateLimit-Tokens-Remaining`   | Remaining tokens in current 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                                  |