portkey-ai

library2.3.1pypypi✓ verified 87d ago

The Portkey.ai Python client library provides an interface to the Portkey API, a unified AI gateway for managing, monitoring, and routing large language model (LLM) requests. It offers features like observability, caching, load balancing, and prompt management across various LLM providers. The library is actively maintained, with frequent updates.

llm-agents ai-ml observability

pip install portkey-ai

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PORTKEY-AI

portkey-ai

llm-agentspythonv2.3.1

Install

5.3s avg

Import

5358ms

Disk

49MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.3.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 5.563s · 50.7MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 5.3s · import 5.153s · 50MB

49MB installed

● package 49MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Portkey

✓ from portkey_ai import Portkey

✗ import portkey_ai

The primary synchronous client class is `Portkey`, imported directly from the `portkey_ai` package.

AsyncPortkey

✓ from portkey_ai import AsyncPortkey

For asynchronous operations, `AsyncPortkey` is available.

Initializes the Portkey client using the `PORTKEY_API_KEY` environment variable and directs requests through a configured provider slug (e.g., `@openai-prod`). It then makes a chat completion request using a model available via that provider.

import os from portkey_ai import Portkey # Set your Portkey API key as an environment variable: export PORTKEY_API_KEY="pk-sk-..." # If using a direct provider (e.g., OpenAI) without Portkey Virtual Keys, # you might also need its API key, e.g.: export OPENAI_API_KEY="sk-..." portkey_client = Portkey( api_key=os.environ.get('PORTKEY_API_KEY', ''), # Use a provider slug from your Portkey Model Catalog # e.g., "@openai-prod" if configured in Portkey provider="@openai-prod" ) try: response = portkey_client.chat.completions.create( messages=[ {"role": "user", "content": "What is the capital of France?"} ], # Model name configured under the "@openai-prod" provider in Portkey model="gpt-4o" ) print(response.choices[0].message.content) except Exception as e: print(f"An error occurred: {e}")

Debug

Known issues

breakingMajor version 2.0.0 introduced significant internal changes, including vendoring a specific version of the OpenAI SDK. While Portkey aims for compatibility, direct dependencies or specific behaviors of the underlying OpenAI client might have changed. This could require adjustments for complex integrations that rely on specific OpenAI client versions or internal workings.

fix

Review the Portkey and OpenAI SDK changelogs for relevant updates. Test existing integrations thoroughly after upgrading to v2.0.0 or later. Consult Portkey documentation for updated usage patterns, especially for advanced configurations or when directly interacting with vendored client internals.

affects: >=2.0.0

gotchaPortkey utilizes its own `PORTKEY_API_KEY` for authenticating with the Portkey gateway. Separately, your actual LLM provider API keys (e.g., OpenAI, Anthropic) must be configured within Portkey's 'Virtual Keys' or 'Model Catalog' dashboard, or provided via the `Authorization` parameter in the `Portkey` client constructor. Simply passing a provider's API key to `Portkey(api_key="...")` is incorrect for LLM provider authentication.

fix

Ensure `PORTKEY_API_KEY` is set for the `Portkey` client. Manage LLM provider keys via Portkey's dashboard (recommended) and use provider slugs (e.g., `@openai-prod`) or `config` objects. Alternatively, provide provider-specific `Authorization` headers to the `Portkey` client for direct pass-through of provider keys.

affects: All versions

gotchaWhen using the `provider` parameter, Portkey often expects models to be specified in a `@provider-slug/model-name` format (e.g., `@openai-prod/gpt-4o`). Simply providing `model="gpt-4o"` without the appropriate provider slug prefix, or without a `config` object defining the routing, may lead to errors or incorrect routing.

fix

Always use the full `@provider-slug/model-name` format for the `model` parameter when using the `provider` argument in the client constructor. Alternatively, define a `config` object for the `Portkey` client that specifies the desired routing strategy and provider details. Refer to the Portkey Model Catalog documentation for valid provider slugs and model names.

affects: All versions

Errors

Common errors & fixes

Error: Unauthorized (401) / Incorrect API key provided

Your Portkey API key is either missing, invalid, or expired, preventing authentication with the Portkey gateway.

fix

Ensure the PORTKEY_API_KEY environment variable is set correctly with an active API key from your Portkey dashboard, or pass it directly to the Portkey client constructor.

Error: Missing API key for provider

The API key for the underlying Large Language Model (LLM) provider (e.g., OpenAI, Anthropic) is not configured in Portkey or passed in the request.

fix

Set the appropriate provider API key (e.g., OPENAI_API_KEY) in your environment variables, configure it as a virtual key in the Portkey dashboard, or pass it via `Authorization` header in the Portkey client.

Either x-portkey-config or x-portkey-provider header is required

When using Portkey as a gateway, the request is missing mandatory headers that specify which Portkey configuration or provider to route the request through.

fix

Include either the `x-portkey-config` header with your configuration slug or the `x-portkey-provider` header with the target provider slug in your API request.

Error: Model not supported / The specified model does not exist or access is restricted.

The model name provided in the request is incorrect, not available for your account through Portkey, or the underlying provider does not support it.

fix

Verify the model name against the Portkey model catalog or the provider's documentation, and ensure your Portkey configuration or provider settings allow access to that model.

Error: Rate limit exceeded.

You have exceeded the allowed number of requests to the LLM provider or the Portkey gateway within a given time frame.

fix

Implement retry logic with exponential backoff, use Portkey's built-in rate limit management features, or check your usage and limits on the Portkey dashboard and the LLM provider's platform.

Upgrade

Version history

2.3.1latest on PyPI · released May 15, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Portkey-AI/portkey-python-sdk ↗

packagehttps://pypi.org/project/portkey-ai/ ↗

homepagehttps://portkey.ai ↗