🍰 PromptLayer

Version, test, and monitor every prompt and agent with robust evals, tracing, and regression sets.

---

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

AI coding agents

• JavaScript SDK guide: https://docs.promptlayer.com/sdks/javascript
• Curated docs index (llms.txt): https://docs.promptlayer.com/llms.txt
• Full docs corpus (llms-full.txt): https://docs.promptlayer.com/llms-full.txt

Install PromptLayer skill files and the Docs MCP server into your coding agents:

npx promptlayer setup

This writes the PromptLayer docs skill and the SDK evals skill (sdk-eval-builder) for Cursor and Claude Code, and adds the Docs MCP server (https://docs.promptlayer.com/mcp) to their project configs. Useful variants:

npx promptlayer setup skills
npx promptlayer setup mcp
npx promptlayer setup --agent cursor --agent claude
npx promptlayer setup --force

Installation

npm install promptlayer

Optional peer dependencies (learn more):

npm install promptlayer @openai/agents
npm install promptlayer @anthropic-ai/claude-agent-sdk

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:

import { PromptLayer } from "promptlayer";

async function main() {
  const pl = new PromptLayer({
    apiKey: process.env.PROMPTLAYER_API_KEY,
  });

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

  console.log(prompt?.prompt_template);
}

main();

SDK methods that make network requests return promises.

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

npm install openai

import OpenAI from "openai";
import { PromptLayer } from "promptlayer";

async function main() {
  const pl = new PromptLayer({
    apiKey: process.env.PROMPTLAYER_API_KEY,
  });

  const PromptLayerOpenAI: typeof OpenAI = pl.OpenAI;
  const openai = new PromptLayerOpenAI();

  const response = await openai.chat.completions.create({
    model: "gpt-4.1-mini",
    messages: [{ role: "user", content: "Say hello in one short sentence." }],
    // @ts-ignore PromptLayer proxy option
    pl_tags: ["proxy-example"],
  });

  console.log(response);
}

main();

Configuration

Client Options

PromptLayer(...) accepts these parameters:

• apiKey: string | undefined: Your PromptLayer API key. If omitted, the SDK looks for PROMPTLAYER_API_KEY.
• enableTracing: boolean = false: Enables OpenTelemetry tracing export to PromptLayer.
• baseURL: string | undefined: Overrides the PromptLayer API base URL. If omitted, the SDK uses PROMPTLAYER_BASE_URL or the default API URL.
• throwOnError: boolean = true: Controls whether SDK methods throw errors or return null or fallback values for many API errors.
• cacheTtlSeconds: number = 0: Enables in-memory prompt-template caching when greater than 0.

Provider Auto-Instrumentation

Tracing registers upstream OpenTelemetry instrumentations for the provider SDKs below. Provider SDKs must load after tracing is configured; ESM applications can preload promptlayer/register.

Provider SDK	Instrumented APIs
OpenAI and Azure OpenAI	chat.completions.create and responses.create, including streams; embeddings.create
Anthropic and Anthropic Vertex	messages.create and beta messages.create, including streams
Google GenAI, including Vertex AI mode	models.generateContent, models.generateContentStream, chat.sendMessage, and chat.sendMessageStream
AWS SDK v3 Bedrock Runtime	Converse

Install @aws-sdk/client-bedrock-runtime in applications that call Bedrock directly. The separate @anthropic-ai/bedrock-sdk client is not included in provider auto-instrumentation.

Message content is captured by default. Set OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false or pass captureContent: false to configureTracing to exclude it. For Bedrock, content capture includes Converse inputs and non-streaming Converse outputs using GenAI message attributes. Content capture can export prompts, responses, tool arguments, and other application data; disable it when that data is not appropriate to send to your configured trace backend.

Runnable coverage examples are available for OpenAI and Azure OpenAI, Anthropic and Anthropic Vertex, Google GenAI and Vertex AI, AWS Bedrock Runtime, and PromptLayer.run with provider overrides. Each API check is isolated so a failure does not prevent the remaining checks from running; optional cloud-hosted checks report which environment variables are missing.

The examples use these defaults when their model environment variables are not set:

Example provider	Default model	Environment override
OpenAI	gpt-4.1-mini	OPENAI_MODEL
OpenAI embeddings	text-embedding-3-small	OPENAI_EMBEDDING_MODEL
Azure OpenAI	OpenAI defaults above	AZURE_OPENAI_MODEL, AZURE_OPENAI_EMBEDDING_MODEL
Anthropic and Anthropic Vertex	claude-sonnet-4-6	ANTHROPIC_MODEL, ANTHROPIC_VERTEX_MODEL
Google GenAI and Vertex AI	gemini-2.5-flash-lite	GOOGLE_GENAI_MODEL, GOOGLE_VERTEX_MODEL

Cloud-hosted checks still require their provider credentials and project configuration.

Environment Variables

The SDK relies on the following environment variables:

Variable	Required	Description
PROMPTLAYER_API_KEY	Yes, unless passed as apiKey	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.
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	No	Controls provider prompt and response content capture. Capture is enabled by default; set this to false to disable it.

Client Resources

The main resources surfaced by PromptLayer are:

Resource	Description
client.templates	Prompt template retrieval, listing, publishing, and cache invalidation.
client.run() and client.runWorkflow()	Helpers for running prompts and workflows.
client.logRequest()	Manual request logging.
client.track	Request annotation utilities for metadata, prompt linkage, scores, and groups.
client.group	Group creation for organizing related requests.
client.wrapWithSpan()	Helper for tracing your own functions and sending those spans to PromptLayer when tracing is enabled.
client.skills	Skill collection pull, publish, and update operations.
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 over OTLP/HTTP (/v1/traces).

Integration Modules

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

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

Error Handling

The SDK throws JavaScript Error instances for validation failures, missing API keys, unsupported providers, and PromptLayer API errors.

Error case	Description
Missing API key	PromptLayer throws if no API key is passed and PROMPTLAYER_API_KEY is not set.
Validation failure	Some resource methods validate inputs before making a request, such as score ranges and skill collection providers.
PromptLayer API error	Non-success PromptLayer responses throw with the API error message when throwOnError is enabled.
Provider SDK error	Provider SDK calls made through client.run() or a provider proxy surface the underlying provider error.
Workflow failure	client.runWorkflow() can return { success: false, message } for some workflow-start failures, and throws for errors such as timeouts or no successful output node.

By default, the client throws these errors. If you initialize PromptLayer with throwOnError: false, many resource methods return null, false, an empty result, or the original provider response instead of throwing 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 cacheTtlSeconds when creating PromptLayer.
• 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(...).