Docs: JavaScript SDK · PromptLayer

The @promptlayerapp/js SDK sends telemetry to https://promptlayer.app/api/v1/requests. It never wraps provider clients — you instrument your own calls.

PromptLayer

Create the client once per process. Required: apiKey and projectId.

constructor typescript

import { PromptLayer } from '@promptlayerapp/js'

const promptlayer = new PromptLayer({
  apiKey: process.env.PROMPTLAYER_API_KEY!,
  projectId: process.env.PROMPTLAYER_PROJECT_ID!,
  baseUrl: process.env.PROMPTLAYER_BASE_URL, // optional
  enabled: true,
  debug: false,
  timeoutMs: 3000,
  maxRetries: 0,
  failureMode: 'swallow',
})

trace()

Start a trace manually. Call trace.end() when finished — it flushes automatically.

trace() typescript

const trace = promptlayer.trace({
  workflow: 'customer_support',
  feature: 'customer_support',
  metadata: { ticket_id: 't_123' },
})

await trace.request({ /* ... */ })
await trace.end()

request()

Record one provider call within a trace. span is required.

trace.request() typescript

await trace.request({
  span: 'classify_ticket',
  provider: 'openai',
  model: 'gpt-4o-mini',
  status: 'success',
  inputTokens: 100,
  outputTokens: 20,
  latencyMs: 800,
})

withTrace()

Preferred pattern — handles trace.end() and flush in a finally block.

withTrace() typescript

await promptlayer.withTrace(
  { workflow: 'customer_support' },
  async (trace) => {
    await trace.request({ /* step 1 */ })
    await trace.request({ /* step 2 */ })
  },
)

flush()

Await all in-flight telemetry sends. Required after standalone trackRequest() calls. withTrace() flushes automatically.

flush() typescript

await promptlayer.trackRequest({
  provider: 'openai',
  model: 'gpt-4o-mini',
  status: 'success',
})

await promptlayer.flush()

Debug mode

Logs send results to console.debug with prefix [PromptLayer].

debug typescript

const promptlayer = new PromptLayer({
  apiKey: process.env.PROMPTLAYER_API_KEY!,
  projectId: process.env.PROMPTLAYER_PROJECT_ID!,
  debug: true,
})

Disabled mode

Skip all network calls — useful for tests or local runs without telemetry.

enabled: false typescript

const promptlayer = new PromptLayer({
  apiKey: process.env.PROMPTLAYER_API_KEY!,
  projectId: process.env.PROMPTLAYER_PROJECT_ID!,
  enabled: false,
})