PromptLayer Python Library

To trace direct OpenAI SDK calls using OpenTelemetry, install the instrumentation extra:

pip install "promptlayer[otel-genai-instrumentation]" openai

Option 1: Using a PromptLayer client

Enable tracing on the client, and then use the standard OpenAI client. This uses the PromptLayer-managed tracer provider.

from openai import OpenAI
from promptlayer import PromptLayer

promptlayer_client = PromptLayer(api_key="pl_xxxxx", enable_tracing=True)
openai_client = OpenAI()

response = openai_client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "Hello."}],
)

Option 2: Using instrument_openai()

If you don't want to create a PromptLayer client, you can use instrument_openai(). This reads the API key and endpoint from the environment.

from openai import OpenAI
from promptlayer import instrument_openai

tracer_provider = instrument_openai()
openai_client = OpenAI()

When initializing PromptLayer(...) or AsyncPromptLayer(...), you can pass the following parameters:

• api_key: str | None = None: Your PromptLayer API key. If omitted, the SDK looks for PROMPTLAYER_API_KEY.
• enable_tracing: bool = False: Enables OpenTelemetry tracing export to PromptLayer and auto-instruments the OpenAI SDK when the tracing extra is installed.
• base_url: str | None = None: Overrides the PromptLayer API base URL. If omitted, the SDK uses PROMPTLAYER_BASE_URL or the default API URL.
• throw_on_error: bool = True: Controls whether SDK methods raise PromptLayer exceptions or return None for many API errors.
• cache_ttl_seconds: int = 0: Enables in-memory prompt-template caching when greater than 0.
• tracer_provider: TracerProvider | None = None: Uses an application-owned OpenTelemetry SDK tracer provider instead of the default PromptLayer-managed provider.

To use PromptLayer, instantiate the PromptLayer class (for synchronous operations) or AsyncPromptLayer (for asynchronous operations). You must provide an api_key, which can also be set via the PROMPTLAYER_API_KEY environment variable.

Parameters:

• api_key (str): Your PromptLayer API key.
• enable_tracing (bool): Whether to enable OpenTelemetry tracing. Defaults to False.
• base_url (str): The API base URL. Defaults to https://api.promptlayer.com or the PROMPTLAYER_BASE_URL environment variable.
• throw_on_error (bool): If True, the client will raise exceptions on API errors. Defaults to True.
• cache_ttl_seconds (int): Time-to-live for the template cache in seconds. Defaults to 0 (no cache).
• tracer_provider: An optional OpenTelemetry tracer provider.

from promptlayer import PromptLayer

# Using environment variable PROMPTLAYER_API_KEY
pl = PromptLayer(enable_tracing=True)

# Explicitly passing API key
pl = PromptLayer(api_key="your_api_key_here", cache_ttl_seconds=3600)

The SDK raises PromptLayerError for failures. You can control whether these are raised or return None by setting throw_on_error=False during client initialization.

Common error subclasses:

• PromptLayerValidationError: Invalid input passed to the SDK.
• PromptLayerAPIConnectionError: Could not connect to PromptLayer.
• PromptLayerAPITimeoutError: Request or workflow run timed out.
• PromptLayerAuthenticationError: Missing or invalid API key.
• PromptLayerPermissionDeniedError: API key lacks permission.
• PromptLayerNotFoundError: Resource (prompt, workflow, etc.) not found.
• PromptLayerBadRequestError: Malformed request or invalid parameters.
• PromptLayerConflictError: Request conflicts with current resource state.
• PromptLayerUnprocessableEntityError: Well-formed but semantically invalid.
• PromptLayerRateLimitError: Rate limiting applied.
• PromptLayerInternalServerError: 5xx server error.
• PromptLayerAPIStatusError: Other non-success API responses.

Scorecards are the preferred API for table scoring workflows. Use client.tables.sheets.scorecards to manage them.

Configure a scorecard

await client.tables.sheets.scorecards.configure(
    table_id,
    sheet_id,
    {
        "name": "Quality Scorecard",
        "evaluated_column_ids": [],
        "aggregation": {
            "method": "weighted_mean",
            "required_step_failure_behavior": "fail",
            "pass_threshold": 0.8,
            "warn_threshold": 0.6,
        },
        "steps": [],
    },
)

Migrate legacy scores

await client.tables.sheets.scorecards.migrate_legacy_score(
    table_id,
    sheet_id,
    {"delete_legacy_score": False},
)

Recalculate and fetch results

run = await client.tables.sheets.scorecards.recalculate(table_id, sheet_id)

result = await client.tables.sheets.scorecards.get_calculation(
    table_id,
    sheet_id,
    run["calculation_id"],
)

Fetch row breakdowns

rows = await client.tables.sheets.scorecards.list_rows(
    table_id,
    sheet_id,
    {
        "calculation_id": run["calculation_id"],
        "verdict": "fail",
    },
)

row = await client.tables.sheets.scorecards.get_row(
    table_id,
    sheet_id,
    0,
    {"calculation_id": run["calculation_id"]},
)