> ## 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 integrate HoneyHive with Portkey

> Integrate HoneyHive with Portkey AI Gateway to trace routed LLM requests. Capture gateway spans, provider calls, and metadata from Portkey-enabled apps.

[Portkey](https://portkey.ai/) is an AI gateway that provides a unified API to access 1,600+ LLMs with features like fallbacks, load balancing, caching, and budget limits. Since Portkey exposes an OpenAI-compatible API, HoneyHive automatically traces all requests routed through the gateway via the OpenAI instrumentor.

## Quick Start

<Tip>
  **Add HoneyHive tracing to your Portkey-routed app.** Initialize HoneyHive with the OpenAI instrumentor, then point your OpenAI client to Portkey's gateway. All completions are automatically traced regardless of the underlying provider.
</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-instrumentation-openai openai portkey-ai
```

```python theme={null}
import os
from openai import OpenAI
from portkey_ai import PORTKEY_GATEWAY_URL
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)

# Point OpenAI client to Portkey's gateway
client = OpenAI(
    api_key=os.getenv("PORTKEY_API_KEY"),
    base_url=PORTKEY_GATEWAY_URL
)

# Use @provider-slug/model format from Portkey's Model Catalog
response = client.chat.completions.create(
    model="@openai-prod/gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello, world!"}]
)
print(response.choices[0].message.content)
```

The `@provider-slug/model` format routes requests to the correct provider. Set up providers in Portkey's [Model Catalog](https://app.portkey.ai/) by adding your provider credentials and naming the provider (e.g., `openai-prod`). The slug becomes `@openai-prod`.

## What Gets Traced

The OpenAI instrumentor captures all calls through Portkey's gateway:

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

No Portkey-specific instrumentor is required. The OpenAI instrumentor works because Portkey implements the OpenAI-compatible API format.

***

## Example: Multi-Provider Routing

Switch between providers by changing the model slug. Each `@provider-slug` maps to credentials you configured in Portkey's Model Catalog:

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

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

client = OpenAI(
    api_key=os.getenv("PORTKEY_API_KEY"),
    base_url=PORTKEY_GATEWAY_URL
)

@trace
def query_multiple_providers():
    # Route to OpenAI
    openai_response = client.chat.completions.create(
        model="@openai-prod/gpt-4o-mini",
        messages=[{"role": "user", "content": "Explain quantum computing briefly."}]
    )

    # Route to Anthropic
    anthropic_response = client.chat.completions.create(
        model="@anthropic-prod/claude-sonnet-4-5-20250929",
        messages=[{"role": "user", "content": "Explain quantum computing briefly."}],
        max_tokens=250
    )

    return openai_response, anthropic_response

query_multiple_providers()
```

Add each provider in the [Model Catalog](https://app.portkey.ai/) with a name like `openai-prod` or `anthropic-prod`. The provider slug becomes `@openai-prod` or `@anthropic-prod`.

***

## Example: Fallbacks and Load Balancing

Use a Portkey config to define fallback or load-balancing rules. Create the config in the [Portkey dashboard](https://app.portkey.ai/) and pass its ID via the `config` header. HoneyHive traces whichever provider handles the request:

```python theme={null}
import os
from openai import OpenAI
from portkey_ai import PORTKEY_GATEWAY_URL, createHeaders
from honeyhive import HoneyHiveTracer, trace
from openinference.instrumentation.openai import OpenAIInstrumentor

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

client = OpenAI(
    api_key=os.getenv("PORTKEY_API_KEY"),
    base_url=PORTKEY_GATEWAY_URL,
    default_headers=createHeaders(
        api_key=os.getenv("PORTKEY_API_KEY"),
        config=os.getenv("PORTKEY_CONFIG_ID")
    )
)

@trace
def resilient_completion(prompt: str):
    return client.chat.completions.create(
        model="@openai-prod/gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )

resilient_completion("What are the benefits of AI observability?")
```

Example config JSON for fallback between providers:

```json theme={null}
{
  "strategy": { "mode": "fallback" },
  "targets": [
    { "override_params": { "model": "@openai-prod/gpt-4o" } },
    { "override_params": { "model": "@anthropic-prod/claude-sonnet-4-5-20250929" } }
  ]
}
```

See [Portkey's configs docs](https://portkey.ai/docs/product/ai-gateway/configs) for more patterns including load balancing, conditional routing, and caching.

***

## Environment Configuration

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

# Portkey
export PORTKEY_API_KEY="your-portkey-api-key"
export PORTKEY_CONFIG_ID="your-config-id"   # optional, for fallback/routing configs
```

***

## Troubleshooting

### Traces not appearing

1. **Check the instrumentor** - Ensure `OpenAIInstrumentor` is initialized with `tracer_provider=tracer.provider` before making any calls
2. **Verify `base_url`** - The OpenAI client must point to Portkey's gateway (`PORTKEY_GATEWAY_URL` or `https://api.portkey.ai/v1`)
3. **Check `HH_API_KEY`** - Ensure your HoneyHive API key is set correctly

### Requests failing with provider errors

1. **Check the model slug** - Use the `@provider-slug/model-name` format (e.g., `@openai-prod/gpt-4o-mini`). The provider slug must match a provider you configured in [Model Catalog](https://app.portkey.ai/)
2. **Verify model name** - Use the model name expected by the target provider (e.g., `gpt-4o-mini` for OpenAI, `claude-sonnet-4-5-20250929` for Anthropic)

### Duplicate spans

If you use both a Portkey client and a direct OpenAI client in the same app, both will be traced by the same instrumentor. Use HoneyHive's `@trace` decorator to group related calls into named spans for clarity.

***

## Related

<CardGroup cols={2}>
  <Card title="OpenAI Integration" icon="bolt" href="/v2/integrations/openai">
    Base OpenAI integration that powers Portkey tracing
  </Card>

  <Card title="LiteLLM Integration" icon="shuffle" href="/v2/integrations/litellm">
    Alternative multi-provider gateway with HoneyHive support
  </Card>

  <Card title="Use Portkey for LLM Evaluators" icon="robot" href="/v2/evaluators/portkey">
    Route LLM evaluator calls through Portkey to access any supported model
  </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

* [Portkey Documentation](https://portkey.ai/docs)
* [Portkey HoneyHive Integration Guide](https://portkey.ai/docs/integrations/tracing-providers/honeyhive)
* [Portkey AI Gateway Configs](https://portkey.ai/docs/product/ai-gateway/configs)
* [Portkey Model Catalog](https://portkey.ai/docs/product/ai-gateway/model-catalog)