To get started, create an account by clicking “Log in” on PromptLayer. Once logged in, click the button to create an API key and save this in a secure location (Guide to Using Env Vars).
Once you have that all set up, install PromptLayer using pip.
PromptLayer python library has support for OpenAI, Anthropic, and other LLM providers!
Set up a PromptLayer client in your python file.
from promptlayer import PromptLayer
promptlayer_client = PromptLayer()
promptlayer_client = PromptLayer(api_key="pl_****", base_url="https://api.promptlayer.com")
Using the run Method (Recommended)
The easiest way to use PromptLayer is with the run() method. It fetches a prompt template from the Prompt Registry, executes it against your configured LLM provider, and logs the result — all in one call.
from promptlayer import PromptLayer
promptlayer_client = PromptLayer()
response = promptlayer_client.run(
prompt_name="my-prompt",
input_variables={"topic": "poetry"},
tags=["getting-started"],
metadata={"user_id": "123"}
)
print(response["prompt_blueprint"]["prompt_template"]["messages"][-1]["content"])
Your LLM API keys (OpenAI, Anthropic, etc.) are never sent to our servers. All LLM requests are made locally from your machine, PromptLayer just logs the request.
run() method works with any provider configured in your prompt template — OpenAI, Anthropic, Google, and more. See the Run documentation for full details.
After making your first few requests, you should be able to see them in the PromptLayer dashboard!
Custom Logging with log_request
If you need more control — for example, using your own LLM client, a custom provider, or background processing — you can use log_request to manually log requests to PromptLayer.
from openai import OpenAI
from promptlayer import PromptLayer
import time
pl_client = PromptLayer()
client = OpenAI()
messages = [
{"role": "system", "content": "You are an AI."},
{"role": "user", "content": "Compose a poem please."}
]
request_start_time = time.time()
completion = client.chat.completions.create(
model="gpt-4o",
messages=messages
)
request_end_time = time.time()
# Log to PromptLayer
pl_client.log_request(
provider="openai",
model="gpt-4o",
input={"type": "chat", "messages": [
{"role": m["role"], "content": [{"type": "text", "text": m["content"]}]}
for m in messages
]},
output={"type": "chat", "messages": [
{"role": "assistant", "content": [{"type": "text", "text": completion.choices[0].message.content}]}
]},
request_start_time=request_start_time,
request_end_time=request_end_time,
tags=["getting-started"]
)
import anthropic
from promptlayer import PromptLayer
import time
pl_client = PromptLayer()
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "How many toes do dogs have?"}]
request_start_time = time.time()
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=100,
messages=messages
)
request_end_time = time.time()
# Log to PromptLayer
pl_client.log_request(
provider="anthropic",
model="claude-sonnet-4-20250514",
input={"type": "chat", "messages": [
{"role": m["role"], "content": [{"type": "text", "text": m["content"]}]}
for m in messages
]},
output={"type": "chat", "messages": [
{"role": "assistant", "content": [{"type": "text", "text": response.content[0].text}]}
]},
request_start_time=request_start_time,
request_end_time=request_end_time,
tags=["animal-toes"]
)
Error Handling
PromptLayer provides robust error handling with specialized exception classes and configurable error behavior.
Exception Classes
The library includes specific exception types following industry best practices:
from promptlayer import (
PromptLayerAPIError, # General API errors
PromptLayerBadRequestError, # 400 errors
PromptLayerAuthenticationError, # 401 errors
PromptLayerNotFoundError, # 404 errors
PromptLayerValidationError, # Input validation errors
PromptLayerAPIConnectionError, # Connection failures
PromptLayerAPITimeoutError, # Timeout errors
PromptLayerRateLimitError, # 429 rate limit errors
)
Using throw_on_error
By default, PromptLayer throws exceptions when errors occur. You can control this behavior using the throw_on_error parameter:
from promptlayer import PromptLayer
# Default behavior: throws exceptions on errors
promptlayer_client = PromptLayer(api_key="pl_****", throw_on_error=True)
# Alternative: logs warnings instead of throwing exceptions
promptlayer_client = PromptLayer(api_key="pl_****", throw_on_error=False)
from promptlayer import PromptLayer, PromptLayerNotFoundError, PromptLayerValidationError
promptlayer_client = PromptLayer()
try:
# Attempt to get a template that might not exist
template = promptlayer_client.templates.get("NonExistentTemplate")
except PromptLayerNotFoundError as e:
print(f"Template not found: {e}")
except PromptLayerValidationError as e:
print(f"Invalid input: {e}")
from promptlayer import PromptLayer
# Initialize with throw_on_error=False to get warnings instead of exceptions
promptlayer_client = PromptLayer(throw_on_error=False)
# This will log a warning instead of throwing an exception if the template doesn't exist
template = promptlayer_client.templates.get("NonExistentTemplate")
# Returns None if not found, with a warning logged
Automatic Retry Mechanism
PromptLayer includes a built-in retry mechanism to handle transient failures gracefully. This ensures your application remains resilient when temporary issues occur.
Retry Behavior:
- Total Attempts: 4 attempts (1 initial + 3 retries)
- Exponential Backoff: Retries wait progressively longer between attempts (2s, 4s, 8s)
- Max Wait Time: 15 seconds maximum wait between retries
What Triggers Retries:
- 5xx Server Errors: Internal server errors, service unavailable, etc.
- 429 Rate Limit Errors: When rate limits are exceeded
What Fails Immediately (No Retries):
- Connection Errors: Network connectivity issues
- Timeout Errors: Request timeouts
- 4xx Client Errors (except 429): Bad requests, authentication errors, not found, etc.
The retry mechanism operates transparently in the background. You don’t need to implement retry logic yourself - PromptLayer handles it automatically for recoverable errors.
Logging
PromptLayer uses Python’s built-in logging module for all log output:
import logging
from promptlayer import PromptLayer
# Configure logging to see PromptLayer logs
logging.basicConfig(level=logging.INFO)
promptlayer_client = PromptLayer()
# Now you'll see log output from PromptLayer operations
import logging
# Get the PromptLayer logger
logger = logging.getLogger("promptlayer")
# Set to WARNING to only see warnings and errors
logger.setLevel(logging.WARNING)
# Set to DEBUG to see detailed information
logger.setLevel(logging.DEBUG)
import logging
from promptlayer import PromptLayer
# Set up logging to see retry attempts
logging.basicConfig(
level=logging.WARNING,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
promptlayer_client = PromptLayer()
# If a retry occurs, you'll see log messages like:
# "Retrying in 2 seconds..."
# "Retrying in 4 seconds..."
Async Support
PromptLayer supports asynchronous operations, ideal for managing concurrent tasks in non-blocking environments like web servers, microservices, or Jupyter notebooks.
Initializing the Async Client
To use asynchronous non-blocking methods, initialize AsyncPromptLayer as shown:
from promptlayer import AsyncPromptLayer
# Initialize an asynchronous client with your API key
async_promptlayer_client = AsyncPromptLayer(api_key="pl_****")
Async Usage Examples
The asynchronous client functions similarly to the synchronous version, but allows for non-blocking execution with asyncio. Below are example uses.
Example 1: Async Template Management
Use asynchronous methods to manage templates:
import asyncio
from promptlayer import AsyncPromptLayer
async def main():
async_promptlayer_client = AsyncPromptLayer(api_key="pl_****")
# Fetch a template asynchronously
template = await async_promptlayer_client.templates.get("Test1")
print(template)
# Fetch all templates asynchronously
templates = await async_promptlayer_client.templates.all()
print(templates)
# Run the async function
asyncio.run(main())
Example 2: Async Agent Execution
Run Agents asynchronously for better efficiency:
import asyncio
from promptlayer import AsyncPromptLayer
async def main():
async_promptlayer_client = AsyncPromptLayer(api_key="pl_****")
response = await async_promptlayer_client.run_workflow(
workflow_name="example_agent",
workflow_version=1,
input_variables={"num1": "1", "num2": "2"},
return_all_outputs=True,
)
print(response)
# Run the async function
asyncio.run(main())
Example 3: Async Tracking and Logging
Track and log requests asynchronously:
import asyncio
from promptlayer import AsyncPromptLayer
async def main():
async_promptlayer_client = AsyncPromptLayer(api_key="pl_****")
# Track metadata asynchronously
request_id = "pl_request_id_example"
await async_promptlayer_client.track.metadata(request_id, {"key": "value"})
# Log request asynchronously (for detailed logging, refer to the custom logging page)
await async_promptlayer_client.log_request(
provider="openai",
model="gpt-3.5-turbo",
input=prompt_template,
output=output_template,
request_start_time=1630945600,
request_end_time=1630945605,
)
# Run the async function
asyncio.run(main())
Example 4: Asynchronous Prompt Execution with run Method
You can execute prompt templates asynchronously using the run method. This allows you to run a prompt template by name with given input variables.
import asyncio
from promptlayer import AsyncPromptLayer
async def main():
async_promptlayer_client = AsyncPromptLayer(api_key="pl_****")
# Execute a prompt template asynchronously
response = await async_promptlayer_client.run(
prompt_name="TestPrompt",
input_variables={"variable1": "value1", "variable2": "value2"}
)
print(response)
# Run the async function
asyncio.run(main())
Example 5: Asynchronous Streaming Prompt Execution with run Method
You can run streaming prompt template using the run method as well.
import asyncio
import os
from promptlayer import AsyncPromptLayer
async def main():
async_promptlayer_client = AsyncPromptLayer(
api_key=os.environ.get("PROMPTLAYER_API_KEY")
)
response_generator = await async_promptlayer_client.run(
prompt_name="TestPrompt",
input_variables={"variable1": "value1", "variable2": "value2"}, stream=True
)
final_response = ""
async for response in response_generator:
# Access raw streaming response
print("Raw streaming response:", response["raw_response"])
# Access progressively built prompt blueprint
if response["prompt_blueprint"]:
current_response = response["prompt_blueprint"]["prompt_template"]["messages"][-1]
if current_response.get("content"):
print(f"Current response: {current_response['content']}")
# Run the async function
asyncio.run(main())
prompt_blueprint, allowing you to track how the response is constructed in real-time.
Supported Methods: Synchronous vs. Asynchronous
The following table provides an overview of the methods currently available in both synchronous and asynchronous versions of the PromptLayer client:
| Method | Description | Synchronous Version | Asynchronous Version |
|---|
templates.get() | Retrieves a template by name. | promptlayer_client.templates.get() | async_promptlayer_client.templates.get() |
templates.all() | Retrieves all templates. | promptlayer_client.templates.all() | async_promptlayer_client.templates.all() |
run() | Executes a prompt template. | promptlayer_client.run() | async_promptlayer_client.run() |
run_workflow() | Executes an Agent. | promptlayer_client.run_workflow() | async_promptlayer_client.run_workflow() |
track.metadata() | Tracks metadata. | promptlayer_client.track.metadata() | async_promptlayer_client.track.metadata() |
track.group() | Tracks a group. | promptlayer_client.track.group() | async_promptlayer_client.track.group() |
track.prompt() | Tracks a prompt. | promptlayer_client.track.prompt() | async_promptlayer_client.track.prompt() |
track.score() | Tracks a score. | promptlayer_client.track.score() | async_promptlayer_client.track.score() |
group.create() | Creates a new group. | promptlayer_client.group.create() | async_promptlayer_client.group.create() |
log_request() | Logs a request. | promptlayer_client.log_request() | async_promptlayer_client.log_request() |
Note: All asynchronous methods require an active event loop. Use them within an async function and run the function using asyncio.run() or another method suitable for managing event loops (e.g., await in Jupyter notebooks).
Want to say hi 👋, submit a feature request, or report a bug? ✉️ Contact us 
