This library provides convenient access to the PromptLayer API from applications written in python.

Installation

pip install promptlayer

Optional extras (learn more):

pip install "promptlayer[openai-agents]"
pip install "promptlayer[claude-agents]"

Quick Start

To follow along, you need a PromptLayer API key. Once logged in, go to Settings to generate a key.

Create a client and fetch a prompt template from PromptLayer:

from promptlayer import PromptLayer

pl = PromptLayer(api_key="pl_xxxxx")

prompt = pl.templates.get(
    "support-reply",
    {
        "input_variables": {
            "customer_name": "Ada",
            "question": "How do I reset my password?",
        }
    },
)

print(prompt["prompt_template"])

Async client:

import asyncio

from promptlayer import AsyncPromptLayer


async def main():
    pl = AsyncPromptLayer(api_key="pl_xxxxx")

    prompt = await pl.templates.get(
        "support-reply",
        {
            "input_variables": {
                "customer_name": "Ada",
                "question": "How do I reset my password?",
            }
        },
    )

    print(prompt["prompt_template"])


asyncio.run(main())

Every method has an async version.

You can also use the client as a proxy around supported provider SDKs:

from promptlayer import PromptLayer

pl = PromptLayer(api_key="pl_xxxxx")
openai = pl.openai

response = openai.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "Say hello in one short sentence."}],
    pl_tags=["proxy-example"],
)

Configuration

Client Options

PromptLayer(...) and AsyncPromptLayer(...) accept these 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 installed OpenAI, Anthropic, Google GenAI, and AWS Bedrock SDKs 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.
• tracing_providers: Iterable[str] | None = None: Selects provider SDKs to auto-instrument. Defaults to all supported providers; pass an empty iterable to export spans without provider SDK auto-instrumentation.

Environment Variables

The SDK relies on the following environment variables:

Variable	Required	Description
PROMPTLAYER_API_KEY	Yes, unless passed as api_key=	API key used to authenticate requests to PromptLayer.
PROMPTLAYER_BASE_URL	No	Overrides the PromptLayer API base URL. Defaults to https://api.promptlayer.com.
PROMPTLAYER_OTLP_TRACES_ENDPOINT	No	Overrides the OTLP trace endpoint (/v1/traces) used when SDK tracing is enabled.
PROMPTLAYER_TRACEPARENT	No	Optional trace context passed through the Claude Agents integration.

Client Resources

The main resources surfaced by PromptLayer and AsyncPromptLayer are:

Resource	Description
client.templates	Prompt template retrieval, listing, publishing, and cache invalidation.
client.run() and client.run_workflow()	Helpers for running prompts and workflows.
client.log_request()	Manual request logging.
client.track	Request annotation utilities for metadata, prompt linkage, scores, and groups.
client.group	Group creation for organizing related requests.
client.traceable()	Decorator for tracing your own functions and sending those spans to PromptLayer when tracing is enabled.
client.skills	Skill collection pull, create, publish, and update operations.
client.tables.sheets.scorecards	Table scorecard configuration, migration, recalculation, and row-level result retrieval.
client.openai and client.anthropic	Provider proxies that wrap those SDKs and log requests to PromptLayer.

Note: When tracing is enabled, spans are exported to PromptLayer using OpenTelemetry.

GenAI SDK Auto-Instrumentation

Install the tracing extra and the provider SDKs used by your application:

pip install "promptlayer[otel-genai-instrumentation]" openai anthropic google-genai boto3

The extra includes the official OpenTelemetry instrumentors for:

Provider	Instrumented APIs
OpenAI and Azure OpenAI	Chat Completions, structured-output parsing, Embeddings, and Responses; sync, async, and streaming
Anthropic and Anthropic Vertex	Messages create, parse, and stream; sync and async
Google GenAI	Generate Content, streaming Generate Content, Embeddings, and supported Interactions releases; Gemini Developer API and Vertex AI modes
AWS Bedrock	Botocore Bedrock Runtime Converse and InvokeModel APIs, including streaming

PromptLayer(enable_tracing=True) auto-instruments every supported provider SDK that is installed:

from anthropic import Anthropic
from promptlayer import PromptLayer

promptlayer_client = PromptLayer(api_key="pl_xxxxx", enable_tracing=True)
anthropic_client = Anthropic()

response = anthropic_client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=256,
    messages=[{"role": "user", "content": "Say hello."}],
)

Advanced OpenTelemetry configurations can select instrumentors explicitly. The google instrumentor supports both Gemini and google-genai clients created with vertexai=True:

from promptlayer import configure_tracing

tracer_provider = configure_tracing(
    providers=("openai", "anthropic", "google", "bedrock"),
)

The openai.azure provider alias selects the underlying OpenAI SDK instrumentor. The amazon.bedrock and aws.bedrock aliases select the Botocore instrumentor. Because Botocore instrumentation operates at the AWS SDK layer, selecting Bedrock also traces other Botocore service calls made by the process.

Message bodies are excluded by OpenTelemetry by default. To include prompts and responses on PromptLayer request logs, opt in before configuring tracing:

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY

Only enable content capture where sending request and response bodies to your configured trace destination is appropriate.

Applications that only use the direct OpenAI SDK can continue to use the OpenAI-specific convenience API:

from openai import OpenAI
from promptlayer import instrument_openai

tracer_provider = instrument_openai()
openai_client = OpenAI()

instrument_openai() reads the PromptLayer API key and endpoint from the environment, is safe to call repeatedly with the same tracer provider, and returns the configured provider so short-lived processes can flush it.

All provider instrumentors in this extra require Python 3.10 or newer. The core PromptLayer package continues to support Python 3.9 without auto-instrumentation.

Table Scorecards

New scorecard APIs are preferred for new table scoring workflows. Legacy /score endpoints remain supported for existing integrations. If both a legacy score configuration and a scorecard exist on the same sheet, /score continues to return legacy score behavior; use the /scorecard endpoints through client.tables.sheets.scorecards to access scorecard state and results.

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 a legacy score safely. delete_legacy_score defaults to False, so migration does not remove legacy score configuration unless you explicitly request it:

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

Recalculate and fetch the calculation:

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"]},
)

Migration caveat: custom legacy scoring cannot be automatically converted into scorecard criteria. Review migrated criteria before relying on scorecard results in production.

Integration Modules

Optional modules that are imported directly rather than accessed through the client:

Module	Description
promptlayer.integrations.openai_agents	Tracing utilities for the openai-agents SDK that instrument agent runs and export their traces to PromptLayer.
promptlayer.integrations.claude_agents	Configuration utilities for the claude-agent-sdk SDK that load the PromptLayer plugin and required environment settings so Claude agent runs send traces to PromptLayer.

Error Handling

The SDK raises PromptLayerError as the base exception for SDK failures, with more specific subclasses for common API and validation cases.

Error type	Description
PromptLayerValidationError	Invalid input passed to the SDK before or during a request.
PromptLayerAPIConnectionError	The SDK could not connect to PromptLayer.
PromptLayerAPITimeoutError	A PromptLayer request or workflow run timed out.
PromptLayerAuthenticationError	Authentication failed, usually because the API key is missing or invalid.
PromptLayerPermissionDeniedError	The API key does not have permission for the requested operation.
PromptLayerNotFoundError	The requested resource, such as a prompt or workflow, was not found.
PromptLayerBadRequestError	The request was malformed or used invalid parameters.
PromptLayerConflictError	The request conflicts with the current state of a resource.
PromptLayerUnprocessableEntityError	The request was well-formed but semantically invalid.
PromptLayerRateLimitError	PromptLayer rejected the request because of rate limiting.
PromptLayerInternalServerError	PromptLayer returned a 5xx server error.
PromptLayerAPIStatusError	Other non-success API responses that do not map to a more specific error type.

By default, the clients raise these exceptions. If you initialize PromptLayer or AsyncPromptLayer with throw_on_error=False, many resource methods return None instead of raising on PromptLayer API errors.

Caching

When enabled, the SDK caches fetched prompt templates in memory for faster repeat reads, locally re-renders them with new variables, and falls back to stale cache on temporary API failures.

• Caching is disabled by default and is enabled by setting cache_ttl_seconds when creating PromptLayer or AsyncPromptLayer.
• The cache applies to prompt templates fetched through client.templates.get(...).
• Cached entries are stored in memory and keyed by prompt name, version, label, provider, and model.
• Requests that include metadata_filters or model_parameter_overrides bypass the cache.
• Templates that require server-side rendering behavior, such as placeholder messages or tool-variable expansion, are not cached for local rendering.
• If a cached template is stale and PromptLayer returns a transient error, the SDK can serve the stale cached version as a fallback.
• You can clear cached entries with client.invalidate(...) or client.templates.invalidate(...).