# promptlayer

> Official PromptLayer SDK

Latest version **2.0.15** (published 2026-08-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install promptlayer
pnpm add promptlayer
yarn add promptlayer
bun add promptlayer
```

Provides the command `promptlayer`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.15 |
| Published | 2026-08-19 |
| First published | 2023-10-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 27 |
| Unpacked size | 2.6 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 14 |
| Maintainers | willbdev, bb220, usamaanser, jpedoeem, t3xrd |

## Links

- npm: https://www.npmjs.com/package/promptlayer
- Repository: https://github.com/MagnivOrg/prompt-layer-js
- Homepage: https://docs.promptlayer.com/sdks/javascript
- Issues: https://github.com/MagnivOrg/prompt-layer-js/issues
- npm.io page: https://npm.io/package/promptlayer

## Dependencies (27)

- [ora](https://npm.io/package/ora.md) ^9.4.1
- [jiti](https://npm.io/package/jiti.md) ^2.7.0
- [dotenv](https://npm.io/package/dotenv.md) ^17.4.2
- [p-retry](https://npm.io/package/p-retry.md) ^6.2.0
- [nunjucks](https://npm.io/package/nunjucks.md) ^3.2.4
- [commander](https://npm.io/package/commander.md) ^14.0.0
- [fast-glob](https://npm.io/package/fast-glob.md) ^3.3.3
- [centrifuge](https://npm.io/package/centrifuge.md) ^5.5.2
- [cli-table3](https://npm.io/package/cli-table3.md) ^0.6.5
- [picocolors](https://npm.io/package/picocolors.md) ^1.1.1
- [@babel/types](https://npm.io/package/@babel/types.md) ^7.28.0
- [@babel/parser](https://npm.io/package/@babel/parser.md) ^7.28.0
- [@babel/traverse](https://npm.io/package/@babel/traverse.md) ^7.28.0
- [@openrouter/sdk](https://npm.io/package/@openrouter/sdk.md) ^1.1.8
- [@babel/generator](https://npm.io/package/@babel/generator.md) ^7.28.0
- [@opentelemetry/api](https://npm.io/package/@opentelemetry/api.md) ^1.9.1
- [@opentelemetry/api-logs](https://npm.io/package/@opentelemetry/api-logs.md) ^0.221.0
- [@opentelemetry/sdk-logs](https://npm.io/package/@opentelemetry/sdk-logs.md) ^0.221.0
- [@opentelemetry/resources](https://npm.io/package/@opentelemetry/resources.md) ^2.10.0
- [@opentelemetry/sdk-trace-base](https://npm.io/package/@opentelemetry/sdk-trace-base.md) ^2.10.0
- [@opentelemetry/sdk-trace-node](https://npm.io/package/@opentelemetry/sdk-trace-node.md) ^2.10.0
- [@opentelemetry/instrumentation](https://npm.io/package/@opentelemetry/instrumentation.md) ^0.221.0
- [@traceloop/instrumentation-anthropic](https://npm.io/package/@traceloop/instrumentation-anthropic.md) ^0.27.0
- [@opentelemetry/instrumentation-openai](https://npm.io/package/@opentelemetry/instrumentation-openai.md) ^0.19.0
- [@opentelemetry/instrumentation-aws-sdk](https://npm.io/package/@opentelemetry/instrumentation-aws-sdk.md) ^0.76.0
- [@opentelemetry/exporter-trace-otlp-http](https://npm.io/package/@opentelemetry/exporter-trace-otlp-http.md) ^0.221.0
- [@traceloop/instrumentation-google-generativeai](https://npm.io/package/@traceloop/instrumentation-google-generativeai.md) ^0.27.0

## Recent versions

- 2.0.15 (latest) — 2026-08-19
- 2.0.14 — 2026-08-19
- 2.0.13 — 2026-08-07
- 2.0.11 — 2026-08-05
- 2.0.10 — 2026-08-05
- 2.0.9 — 2026-08-05
- 2.0.8 — 2026-08-05
- 2.0.7 — 2026-08-04
- 2.0.6 — 2026-08-04
- 2.0.4 — 2026-07-29
- 2.0.3 — 2026-07-28
- 2.0.2 — 2026-07-28
- 2.0.1 — 2026-07-22
- 2.0.0 — 2026-07-22
- 1.3.6 — 2026-07-21
- … 90 more at https://npm.io/package/promptlayer/versions

## README

<div align="center">

# 🍰 PromptLayer

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

<a href="https://nodejs.org/"><img alt="Node.js" src="https://img.shields.io/badge/-Node.js 20+-43853D?style=for-the-badge&logo=node.js&logoColor=white"></a>
<a href="https://docs.promptlayer.com"><img alt="Docs" src="https://custom-icon-badges.herokuapp.com/badge/docs-PL-green.svg?logo=cake&style=for-the-badge"></a>
<a href="https://www.loom.com/share/196c42e43acd4a369d75e9a7374a0850"><img alt="Demo with Loom" src="https://img.shields.io/badge/Demo-loom-552586.svg?logo=loom&style=for-the-badge&labelColor=gray"></a>

---

<div align="left">

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:

```bash
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:

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

## Installation

```bash
npm install promptlayer
```

Optional peer dependencies [(learn more)](#integration-modules):

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

## Quick Start

To follow along, you need a [PromptLayer](https://www.promptlayer.com/) API key. Once logged in, go to Settings to generate a key.

Create a client and fetch a prompt template from PromptLayer:

```ts
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:

```bash
npm install openai
```

```ts
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](examples/tracing/trace_openai.mjs), [Anthropic and Anthropic Vertex](examples/tracing/trace_anthropic.mjs), [Google GenAI and Vertex AI](examples/tracing/trace_google_genai.mjs), [AWS Bedrock Runtime](examples/tracing/trace_bedrock.mjs), and [PromptLayer.run with provider overrides](examples/tracing/trace_promptlayer_run.mjs). 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](https://www.npmjs.com/package/@openai/agents) that instrument agent runs and export their traces to PromptLayer. |
| `promptlayer/claude-agents` | Configuration utilities for the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/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(...)`.

---
_Source: https://npm.io/package/promptlayer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._