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

# How to trace Cloudflare AI Gateway with HoneyHive

> HoneyHive integration for Cloudflare AI Gateway. Trace any HoneyHive-instrumented provider SDK through the gateway with the matching instrumentor.

[Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) sits in front of provider APIs and adds caching, rate limiting, and logging. Keep the provider SDK you already use, point it at the gateway, and call that SDK's HoneyHive instrumentor. HoneyHive traces the SDK, not Cloudflare. No Cloudflare-specific tracer is required. The OpenAI example below is the common case.

## Quick Start

<Tip>
  **Point your OpenAI client at the gateway, then instrument as usual.** `OpenAIInstrumentor` patches the SDK, so chat completions, tools, and token usage are traced regardless of the `base_url`.
</Tip>

<Tip>
  To see where to initialize the tracer for your environment, including AWS Lambda and long-running servers, see [Tracer Initialization](/v2/tracing/tracer-initialization).
</Tip>

```bash theme={null}
pip install "honeyhive[openinference-openai]"
```

```python theme={null}
import os
from openai import OpenAI
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
OpenAIInstrumentor().instrument(tracer_provider=tracer.provider)

account_id = os.getenv("CLOUDFLARE_ACCOUNT_ID")
gateway_id = os.getenv("CLOUDFLARE_GATEWAY_ID")

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=f"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello, world!"}],
)
print(response.choices[0].message.content)
```

Create a gateway in the [Cloudflare dashboard](https://dash.cloudflare.com/), then copy the account ID and gateway ID into the URL. See Cloudflare's [OpenAI provider docs](https://developers.cloudflare.com/ai-gateway/usage/providers/openai/) for the current endpoint shape.

## What Gets Traced

The instrumentor captures gateway-routed SDK calls the same way it captures direct provider calls:

* **Chat completions** - Inputs, outputs, and token usage
* **Tool / function calls** - Arguments and results for each tool invocation
* **Streaming responses** - Streamed completions with aggregated tokens

***

## Authenticated Gateway

If the gateway requires Cloudflare authentication, send the token in `cf-aig-authorization` and keep the provider key as `api_key`:

```python theme={null}
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=f"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai",
    default_headers={
        "cf-aig-authorization": f"Bearer {os.getenv('CF_AIG_TOKEN')}",
    },
)
```

With [BYOK](https://developers.cloudflare.com/ai-gateway/configuration/bring-your-own-keys/) or Unified Billing, Cloudflare stores the provider key. Set `api_key` to the Cloudflare token instead:

```python theme={null}
client = OpenAI(
    api_key=os.getenv("CF_AIG_TOKEN"),
    base_url=f"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai",
)
```

***

## Unified REST API

Cloudflare also exposes OpenAI-compatible endpoints on `api.cloudflare.com`. That client is still the OpenAI SDK, so the same instrumentor traces it. Model names use `author/model` (for example `openai/gpt-4.1-mini`), and the Cloudflare API token is `api_key`:

```python theme={null}
client = OpenAI(
    api_key=os.getenv("CLOUDFLARE_API_TOKEN"),
    base_url=f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1",
    default_headers={"cf-aig-gateway-id": gateway_id},
)
```

`cf-aig-gateway-id` targets a specific gateway. Omit it for third-party models to use the account default. Workers AI models require the header.

See Cloudflare's [REST API](https://developers.cloudflare.com/ai-gateway/usage/rest-api/) for the current model catalog and `/ai/v1/responses` usage. Either base URL traces the same way, so if you already call OpenAI through `gateway.ai.cloudflare.com`, keep that `base_url`.

***

## Other Provider SDKs

HoneyHive patches the SDK you import, not the host. For a provider SDK that accepts a custom base URL:

1. Install the extra from that SDK's [integration page](/v2/integrations/overview)
2. Call its instrumentor with `tracer_provider=tracer.provider`
3. Point the SDK `base_url` (or equivalent, such as `http_options.base_url`) at Cloudflare's provider URL. The `{provider}` segment and any extra path pieces live on Cloudflare's [provider pages](https://developers.cloudflare.com/ai-gateway/usage/providers/). Authenticated gateways still send `cf-aig-authorization`.

HoneyHive ships instrumentors for these provider SDKs:

| SDK                                           | Extra                                   | Instrumentor              |
| --------------------------------------------- | --------------------------------------- | ------------------------- |
| [OpenAI](/v2/integrations/openai)             | `honeyhive[openinference-openai]`       | `OpenAIInstrumentor`      |
| [Anthropic](/v2/integrations/anthropic)       | `honeyhive[openinference-anthropic]`    | `AnthropicInstrumentor`   |
| [Google Gemini](/v2/integrations/gemini)      | `honeyhive[openinference-google-ai]`    | `GoogleGenAIInstrumentor` |
| [Azure OpenAI](/v2/integrations/azure_openai) | `honeyhive[openinference-azure-openai]` | `OpenAIInstrumentor`      |

Do not re-point a boto3 Bedrock client at the gateway. Bedrock uses SigV4, so a `base_url` / `endpoint_url` swap fails. Use the [unified REST API](#unified-rest-api) with the OpenAI SDK (`aws-bedrock/...`), or follow Cloudflare's [Bedrock provider page](https://developers.cloudflare.com/ai-gateway/usage/providers/bedrock/) for the signed request shape.

Cloudflare also proxies Groq, DeepSeek, Mistral, xAI, OpenRouter, and other OpenAI-compatible APIs. Keep `OpenAIInstrumentor` and the **OpenAI SDK**. Change `base_url` to that provider's Cloudflare path. A vendor package that is not `openai` (for example a Groq-only SDK) is not patched.

If HoneyHive has no instrumentor for that SDK, use the [unified REST API](#unified-rest-api) with the OpenAI SDK, or [LiteLLM](/v2/integrations/litellm) if you already route calls through LiteLLM. Raw `fetch` / `curl` is not autotraced.

***

## Environment Configuration

```bash theme={null}
export HH_API_KEY="your-honeyhive-api-key"

export OPENAI_API_KEY="your-openai-api-key"
export CLOUDFLARE_ACCOUNT_ID="your-cloudflare-account-id"
export CLOUDFLARE_GATEWAY_ID="your-gateway-id"

# Authenticated gateway or BYOK / Unified Billing
export CF_AIG_TOKEN="your-cloudflare-ai-gateway-token"

# Unified REST API
export CLOUDFLARE_API_TOKEN="your-cloudflare-api-token"
```

***

## Troubleshooting

### Traces not appearing

1. **Check the instrumentor** - Call the instrumentor for the SDK you import, with `tracer_provider=tracer.provider`, before creating the client or making requests
2. **Confirm you use a provider SDK** - HoneyHive traces SDK methods. Raw `fetch` / `curl` to the gateway is not autotraced
3. **Check `HH_API_KEY`** - Use a project API key from [Settings → Project → API Keys](https://app.us.honeyhive.ai/settings/project/keys)

### Requests fail at the gateway

1. **Account and gateway IDs** - Both path segments must match a gateway in the Cloudflare dashboard
2. **Authenticated gateway** - Provider-specific URLs on `gateway.ai.cloudflare.com` use `cf-aig-authorization`, not `Authorization`, for the Cloudflare token
3. **Model name** - Provider-specific OpenAI URLs use OpenAI model IDs (`gpt-4o-mini`). The unified REST API uses `author/model` for third-party models and `@cf/author/model` for Workers AI
4. **`/ai/run` is not autotraced** - That envelope endpoint is not a provider SDK. Use `/ai/v1/chat/completions` or a provider-native SDK URL if you want HoneyHive to capture the call
5. **Cache hits** - HoneyHive records the completion the SDK receives. A gateway cache hit still returns a completion body, so the span still has inputs, outputs, and any `usage` on that body. The instrumentor does not capture Cloudflare headers such as `cf-aig-cache-status`. Add that with [`enrich_span`](/v2/tracing/custom-spans) if you need it.

***

## Related

<CardGroup cols={2}>
  <Card title="Integrations Overview" icon="plug" href="/v2/integrations/overview">
    Provider SDK instrumentors to pair with a gateway base\_url
  </Card>

  <Card title="OpenAI Integration" icon="bolt" href="/v2/integrations/openai">
    OpenAIInstrumentor used in the Quick Start
  </Card>

  <Card title="Portkey" icon="shuffle" href="/v2/integrations/portkey">
    Another OpenAI-compatible gateway traced the same way
  </Card>

  <Card title="Custom Spans" icon="code" href="/v2/tracing/custom-spans">
    Create spans for business logic around API calls
  </Card>

  <Card title="Enrich Your Traces" icon="sparkles" href="/v2/tutorials/enriching-traces">
    Add user IDs and custom metadata to traces
  </Card>
</CardGroup>

***

## Resources

* [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/)
* [Cloudflare provider list](https://developers.cloudflare.com/ai-gateway/usage/providers/)
* [Cloudflare AI Gateway REST API](https://developers.cloudflare.com/ai-gateway/usage/rest-api/)
* [HoneyHive integrations overview](/v2/integrations/overview)


## Related topics

- [How to trace OpenAI with HoneyHive](/v2/integrations/openai.md)
- [How to trace LiteLLM with HoneyHive](/v2/integrations/litellm.md)
- [How to trace Pydantic AI with HoneyHive](/v2/integrations/pydantic-ai.md)