Skip to main content
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 npm. 
npm install promptlayer
Set up a PromptLayer client in your JavaScript file. 
import { PromptLayer } from "promptlayer";
const promptLayerClient = new PromptLayer();
Optionally, you can specify the API key and base URL in the client. 
const promptLayerClient = new PromptLayer({ apiKey: "pl_****", baseURL: "https://api.promptlayer.com" });
PromptLayer’s JavaScript library is not compatible with client-side (browser) environments. It is designed for use exclusively in server-side runtimes such as Node.js, Bun, or Deno.
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. 
import { PromptLayer } from "promptlayer";
const promptLayerClient = new PromptLayer();

const response = await promptLayerClient.run({
  promptName: "my-prompt",
  inputVariables: { topic: "poetry" },
  tags: ["getting-started"],
  metadata: { user_id: "123" }
});

console.log(response.prompt_blueprint.prompt_template.messages.slice(-1)[0].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.
The run() method works with any provider configured in your prompt template — OpenAI, Anthropic, Google, and more. See the Run documentation for full details.

​
SDK Cache

The PromptLayer JavaScript SDK supports an in-memory template cache to reduce fetch latency and improve resilience when the PromptLayer API has transient failures. Enable cache when you want to:
  • Reduce repeated template fetch latency
  • Lower dependency on real-time PromptLayer API availability
  • Continue serving recently known-good templates during temporary API issues
Pass cacheTtlSeconds when creating a client: 
import { PromptLayer } from "promptlayer";

const promptLayerClient = new PromptLayer({
  apiKey: process.env.PROMPTLAYER_API_KEY,
  cacheTtlSeconds: 300, // each prompt template is cached for 5 minutes
});

​
How It Works

When cache is enabled, templates.get() and run() use this flow:
  1. Return a fresh cached template if available.
  2. If cache is stale or missing, fetch from API and refresh cache.
  3. If API fetch fails with a transient error and a stale template exists, serve the stale template.
Stale fallback applies to transient API failures such as retryable HTTP errors (including 429 and 5xx) and network-level issues.

​
Important Behavior

  • Cache is in-memory and process-local (not shared across machines/containers).
  • Requests with metadataFilters or modelParameterOverrides bypass cache.
  • Publishing via templates.publish() invalidates cache for that prompt name.
  • Call promptLayerClient.invalidate("prompt-name") to clear one prompt from cache.
  • Call promptLayerClient.invalidate() to clear the full SDK cache.

​
Practical Guidance

  • Start with cacheTtlSeconds between 60 and 300.
  • Use a shorter TTL if your prompts change frequently.
  • Use a longer TTL if your prompts are stable and lower latency matters most.
  • Keep throwOnError: true if you want hard failures when no cache entry is available.

​
Custom Logging with logRequest

If you need more control — for example, using your own LLM client, a custom provider, or background processing — you can use logRequest to manually log requests to PromptLayer.

​
OpenAI Example

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

const plClient = new PromptLayer();
const openai = new OpenAI();

const messages = [{ role: "user", content: "Say this is a test" }];

const requestStartTime = Date.now();
const completion = await openai.chat.completions.create({
  messages,
  model: "gpt-4o",
});
const requestEndTime = Date.now();

await plClient.logRequest({
  provider: "openai",
  model: "gpt-4o",
  input: {
    type: "chat",
    messages: messages.map(m => ({
      role: m.role,
      content: [{ type: "text", text: m.content }]
    }))
  },
  output: {
    type: "chat",
    messages: [{
      role: "assistant",
      content: [{ type: "text", text: completion.choices[0].message.content }]
    }]
  },
  requestStartTime,
  requestEndTime,
  tags: ["test"]
});

​
Anthropic Example

import { PromptLayer } from "promptlayer";
import Anthropic from "@anthropic-ai/sdk";

const plClient = new PromptLayer();
const anthropic = new Anthropic();

const messages = [{ role: "user", content: "How many toes do dogs have?" }];

const requestStartTime = Date.now();
const response = await anthropic.messages.create({
  messages,
  model: "claude-sonnet-4-20250514",
  max_tokens: 100,
});
const requestEndTime = Date.now();

await plClient.logRequest({
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  input: {
    type: "chat",
    messages: messages.map(m => ({
      role: m.role,
      content: [{ type: "text", text: m.content }]
    }))
  },
  output: {
    type: "chat",
    messages: [{
      role: "assistant",
      content: [{ type: "text", text: response.content[0].text }]
    }]
  },
  requestStartTime,
  requestEndTime,
  tags: ["test-anthropic-1"]
});
See the Custom Logging documentation and Log Request API Reference for full details.

​
Error Handling

PromptLayer provides robust error handling with configurable error behavior for JavaScript/TypeScript applications.

​
Using throwOnError

By default, PromptLayer throws errors when API requests fail. You can control this behavior using the throwOnError parameter: 
import { PromptLayer } from "promptlayer";

// Default behavior: throws errors on API failures
const promptLayerClient = new PromptLayer({ 
  apiKey: "pl_****", 
  throwOnError: true 
});

// Alternative: logs warnings instead of throwing errors
const promptLayerClient = new PromptLayer({ 
  apiKey: "pl_****", 
  throwOnError: false 
});
Example with error handling: 
import { PromptLayer } from "promptlayer";

const promptLayerClient = new PromptLayer({ apiKey: process.env.PROMPTLAYER_API_KEY });

try {
  // Attempt to get a template that might not exist
  const template = await promptLayerClient.templates.get("NonExistentTemplate");
  console.log(template);
} catch (error) {
  console.error("Failed to get template:", error.message);
}
Example with warnings (throwOnError: false): 
import { PromptLayer } from "promptlayer";

// Initialize with throwOnError: false to get warnings instead of errors
const promptLayerClient = new PromptLayer({ 
  apiKey: process.env.PROMPTLAYER_API_KEY,
  throwOnError: false 
});

// This will log a warning instead of throwing an error if the template doesn't exist
const template = await promptLayerClient.templates.get("NonExistentTemplate");
// Returns null if not found, with a warning logged to console

​
Automatic Retry Mechanism

PromptLayer includes a built-in retry mechanism using the industry-standard p-retry library 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 RateLimit Errors: API RateLimit Error.
  • Network Errors: Connection failures (ENOTFOUND, ECONNREFUSED, ETIMEDOUT, etc.)
What Fails Immediately (No Retries):
  • 4xx Client Errors: Bad requests, authentication errors, not found, validation errors, etc. except for 429 Ratelimit error.
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 logs info to the console before each retry attempt. When a retry occurs, you’ll see log messages like: 
INFO: Retrying PromptLayer API request in 2.0 seconds...
INFO: Retrying PromptLayer API request in 4.0 seconds...
INFO: Retrying PromptLayer API request in 8.0 seconds...
To capture these logs in your application, you can monitor console.info output or use a logging library that intercepts console methods.

​
Edge

PromptLayer can be used with Edge functions. Use either the run() method, logRequest, or our REST API directly. 
import { PromptLayer } from "promptlayer";
const promptLayerClient = new PromptLayer({ apiKey: process.env.PROMPTLAYER_API_KEY });

// Add this line
export const runtime = "edge";

export const POST = async () => {
  const response = await promptLayerClient.run({
    promptName: "my-prompt",
    inputVariables: { question: "What is the capital of France?" },
  });
  const content = response.prompt_blueprint.prompt_template.messages.slice(-1)[0].content;
  return Response.json(content);
};