0
# Langfuse Client
1

2
Langfuse Client (@langfuse/client) is a comprehensive API client for Langfuse, an observability platform for LLM applications. It provides core abstractions for prompt management, dataset operations, experiment execution, scoring, and media handling. The package is designed for universal JavaScript environments including browsers, Node.js, Edge Functions, and other JavaScript runtimes.
3

4
## Package Information
5

6
- **Package Name**: @langfuse/client
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @langfuse/client @langfuse/tracing @opentelemetry/api`
10
- **Version**: 4.2.0
11
- **Dependencies**:
12
  - `@langfuse/core` (workspace)
13
  - `@langfuse/tracing` (workspace)
14
  - `@opentelemetry/api` (peer dependency)
15
  - `mustache`
16

17
## Core Imports
18

19
```typescript { .api }
20
import { LangfuseClient } from '@langfuse/client';
21
```
22

23
CommonJS:
24

25
```javascript
26
const { LangfuseClient } = require('@langfuse/client');
27
```
28

29
Specific imports:
30

31
```typescript { .api }
32
import {
33
  LangfuseClient,
34
  TextPromptClient,
35
  ChatPromptClient,
36
  createEvaluatorFromAutoevals,
37
  // Type imports
38
  type ExperimentParams,
39
  type ExperimentResult,
40
  type ExperimentTask,
41
  type ExperimentItem,
42
  type ExperimentItemResult,
43
  type ExperimentTaskParams,
44
  type Evaluator,
45
  type EvaluatorParams,
46
  type Evaluation,
47
  type RunEvaluator,
48
  type RunEvaluatorParams,
49
  type FetchedDataset,
50
  type RunExperimentOnDataset,
51
  type LinkDatasetItemFunction,
52
  type ChatMessageOrPlaceholder,
53
  type ChatMessageWithPlaceholders,
54
  type LangchainMessagesPlaceholder,
55
  type ChatMessageType
56
} from '@langfuse/client';
57
```
58

59
## Basic Usage
60

61
```typescript
62
import { LangfuseClient } from '@langfuse/client';
63

64
// Initialize client with credentials
65
const langfuse = new LangfuseClient({
66
  publicKey: 'pk_...',
67
  secretKey: 'sk_...',
68
  baseUrl: 'https://cloud.langfuse.com' // optional, default shown
69
});
70

71
// Or use environment variables (LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL)
72
const langfuse = new LangfuseClient();
73

74
// Fetch and compile a prompt
75
const prompt = await langfuse.prompt.get('my-prompt');
76
const compiled = prompt.compile({ variable: 'value' });
77

78
// Get a dataset and run an experiment
79
const dataset = await langfuse.dataset.get('my-dataset');
80
const result = await dataset.runExperiment({
81
  name: 'Model Evaluation',
82
  task: async ({ input }) => myModel.generate(input),
83
  evaluators: [myEvaluator]
84
});
85

86
// Create scores
87
langfuse.score.create({
88
  name: 'quality',
89
  value: 0.85,
90
  traceId: 'trace-123'
91
});
92

93
// Flush pending data before exit
94
await langfuse.flush();
95
```
96

97
## Architecture
98

99
Langfuse Client is built around several key components:
100

101
- **LangfuseClient**: Main entry point providing access to all managers and API client
102
- **Managers**: Specialized managers for different capabilities (PromptManager, DatasetManager, etc.)
103
- **Prompt Clients**: Type-specific clients for text and chat prompts with compilation support
104
- **Experiment Framework**: Comprehensive system for running experiments with evaluation
105
- **Batching & Caching**: Automatic batching for scores and intelligent caching for prompts
106
- **OpenTelemetry Integration**: Built-in support for distributed tracing via OTel spans
107

108
## Capabilities
109

110
### Client Initialization
111

112
The main LangfuseClient class provides centralized access to all Langfuse functionality and direct API access for advanced use cases.
113

114
```typescript { .api }
115
class LangfuseClient {
116
  constructor(params?: LangfuseClientParams);
117

118
  // Manager access
119
  readonly api: LangfuseAPIClient;
120
  readonly prompt: PromptManager;
121
  readonly dataset: DatasetManager;
122
  readonly score: ScoreManager;
123
  readonly media: MediaManager;
124
  readonly experiment: ExperimentManager;
125

126
  // Utility methods
127
  flush(): Promise<void>;
128
  shutdown(): Promise<void>;
129
  getTraceUrl(traceId: string): Promise<string>;
130
}
131

132
interface LangfuseClientParams {
133
  publicKey?: string;
134
  secretKey?: string;
135
  baseUrl?: string;
136
  timeout?: number;
137
  additionalHeaders?: Record<string, string>;
138
}
139
```
140

141
[Client Initialization](./client.md)
142

143
### Prompt Management
144

145
Fetch, create, and manage prompts with built-in caching, version control, and variable substitution. Supports both text and chat prompts with LangChain compatibility.
146

147
```typescript { .api }
148
class PromptManager {
149
  get(name: string, options?: { version?: number; label?: string; cacheTtlSeconds?: number; fallback?: string | ChatMessage[]; maxRetries?: number; type?: "chat" | "text"; fetchTimeoutMs?: number }): Promise<TextPromptClient | ChatPromptClient>;
150
  create(body: CreatePromptRequest): Promise<TextPromptClient | ChatPromptClient>;
151
  update(params: { name: string; version: number; newLabels: string[] }): Promise<Prompt>;
152
}
153

154
class TextPromptClient {
155
  readonly name: string;
156
  readonly version: number;
157
  readonly prompt: string;
158
  readonly config: unknown;
159
  readonly labels: string[];
160
  readonly tags: string[];
161
  readonly isFallback: boolean;
162

163
  compile(variables?: Record<string, string>): string;
164
  getLangchainPrompt(): string;
165
  toJSON(): string;
166
}
167

168
class ChatPromptClient {
169
  readonly name: string;
170
  readonly version: number;
171
  readonly prompt: ChatMessageWithPlaceholders[];
172
  readonly config: unknown;
173
  readonly labels: string[];
174
  readonly tags: string[];
175
  readonly isFallback: boolean;
176

177
  compile(
178
    variables?: Record<string, string>,
179
    placeholders?: Record<string, any>
180
  ): (ChatMessageOrPlaceholder | any)[];
181
  getLangchainPrompt(options?: { placeholders?: Record<string, any> }): (ChatMessage | LangchainMessagesPlaceholder | any)[];
182
  toJSON(): string;
183
}
184
```
185

186
[Prompt Management](./prompts.md)
187

188
### Dataset Operations
189

190
Retrieve datasets with all items, link dataset items to traces for experiment tracking, and run experiments directly on datasets.
191

192
```typescript { .api }
193
class DatasetManager {
194
  get(name: string, options?: { fetchItemsPageSize: number }): Promise<FetchedDataset>;
195
}
196

197
type FetchedDataset = Dataset & {
198
  items: (DatasetItem & { link: LinkDatasetItemFunction })[];
199
  runExperiment: RunExperimentOnDataset;
200
};
201

202
type LinkDatasetItemFunction = (
203
  obj: { otelSpan: Span },
204
  runName: string,
205
  runArgs?: { description?: string; metadata?: any }
206
) => Promise<DatasetRunItem>;
207

208
type RunExperimentOnDataset = (
209
  params: Omit<ExperimentParams<any, any, Record<string, any>>, "data">
210
) => Promise<ExperimentResult<any, any, Record<string, any>>>;
211
```
212

213
[Dataset Operations](./datasets.md)
214

215
### Score Management
216

217
Create and manage scores for traces and observations with automatic batching for efficient API usage.
218

219
```typescript { .api }
220
class ScoreManager {
221
  create(data: ScoreBody): void;
222
  observation(observation: { otelSpan: Span }, data: Omit<ScoreBody, "traceId" | "sessionId" | "observationId" | "datasetRunId">): void;
223
  trace(observation: { otelSpan: Span }, data: Omit<ScoreBody, "traceId" | "sessionId" | "observationId" | "datasetRunId">): void;
224
  activeObservation(data: Omit<ScoreBody, "traceId" | "sessionId" | "observationId" | "datasetRunId">): void;
225
  activeTrace(data: Omit<ScoreBody, "traceId" | "sessionId" | "observationId" | "datasetRunId">): void;
226
  flush(): Promise<void>;
227
  shutdown(): Promise<void>;
228
}
229
```
230

231
[Score Management](./scores.md)
232

233
### Media Reference Resolution
234

235
Resolve media reference strings in objects by fetching media content and converting to base64 data URIs.
236

237
```typescript { .api }
238
class MediaManager {
239
  resolveReferences<T>(params: LangfuseMediaResolveMediaReferencesParams<T>): Promise<T>;
240
  static parseReferenceString(referenceString: string): ParsedMediaReference;
241
}
242

243
type LangfuseMediaResolveMediaReferencesParams<T> = {
244
  obj: T;
245
  resolveWith: "base64DataUri";
246
  maxDepth?: number;
247
};
248
```
249

250
[Media Management](./media.md)
251

252
### Experiment Execution
253

254
Run comprehensive experiments on datasets or custom data with automatic tracing, evaluation, and result formatting.
255

256
```typescript { .api }
257
class ExperimentManager {
258
  run<Input, ExpectedOutput, Metadata extends Record<string, any>>(
259
    config: ExperimentParams<Input, ExpectedOutput, Metadata>
260
  ): Promise<ExperimentResult<Input, ExpectedOutput, Metadata>>;
261
}
262

263
type ExperimentParams<Input, ExpectedOutput, Metadata> = {
264
  name: string;
265
  runName?: string;
266
  description?: string;
267
  metadata?: Record<string, any>;
268
  data: ExperimentItem<Input, ExpectedOutput, Metadata>[];
269
  task: ExperimentTask<Input, ExpectedOutput, Metadata>;
270
  evaluators?: Evaluator<Input, ExpectedOutput, Metadata>[];
271
  runEvaluators?: RunEvaluator<Input, ExpectedOutput, Metadata>[];
272
  maxConcurrency?: number;
273
};
274

275
type ExperimentResult<Input, ExpectedOutput, Metadata> = {
276
  runName: string;
277
  datasetRunId?: string;
278
  datasetRunUrl?: string;
279
  itemResults: ExperimentItemResult<Input, ExpectedOutput, Metadata>[];
280
  runEvaluations: Evaluation[];
281
  format: (options?: { includeItemResults?: boolean }) => Promise<string>;
282
};
283
```
284

285
[Experiment Execution](./experiments.md)
286

287
### AutoEvals Integration
288

289
Convert AutoEvals library evaluators to Langfuse-compatible evaluators for seamless integration.
290

291
```typescript { .api }
292
function createEvaluatorFromAutoevals<E extends CallableFunction>(
293
  autoevalEvaluator: E,
294
  params?: Params<E>
295
): Evaluator;
296
```
297

298
[AutoEvals Integration](./autoevals-adapter.md)
299

300
## Core Types
301

302
### Common Types from @langfuse/core
303

304
```typescript { .api }
305
// Dataset types
306
interface Dataset {
307
  id: string;
308
  name: string;
309
  description?: string;
310
  metadata?: any;
311
  projectId: string;
312
  createdAt: string;
313
  updatedAt: string;
314
}
315

316
interface DatasetItem {
317
  id: string;
318
  datasetId: string;
319
  input: any;
320
  expectedOutput?: any;
321
  metadata?: any;
322
  sourceTraceId?: string;
323
  sourceObservationId?: string;
324
  status: string;
325
  createdAt: string;
326
  updatedAt: string;
327
}
328

329
interface DatasetRunItem {
330
  id: string;
331
  datasetRunId: string;
332
  datasetRunName: string;
333
  datasetItemId: string;
334
  traceId: string;
335
  observationId?: string;
336
  createdAt: string;
337
  updatedAt: string;
338
}
339

340
// Score type
341
interface ScoreBody {
342
  id?: string;
343
  name: string;
344
  value: number | string;
345
  traceId?: string;
346
  observationId?: string;
347
  sessionId?: string;
348
  datasetRunId?: string;
349
  comment?: string;
350
  metadata?: any;
351
  dataType?: 'NUMERIC' | 'CATEGORICAL' | 'BOOLEAN';
352
  environment?: string;
353
}
354

355
// Chat message types
356
interface ChatMessage {
357
  role: string;
358
  content: string;
359
}
360

361
// Prompt types
362
type Prompt = Prompt.Text | Prompt.Chat;
363

364
namespace Prompt {
365
  interface Text {
366
    name: string;
367
    version: number;
368
    type: 'text';
369
    prompt: string;
370
    config: unknown;
371
    labels: string[];
372
    tags: string[];
373
    commitMessage?: string | null;
374
  }
375

376
  interface Chat {
377
    name: string;
378
    version: number;
379
    type: 'chat';
380
    prompt: ChatMessageWithPlaceholders[];
381
    config: unknown;
382
    labels: string[];
383
    tags: string[];
384
    commitMessage?: string | null;
385
  }
386
}
387

388
// Chat message types
389
enum ChatMessageType {
390
  ChatMessage = "chatmessage",
391
  Placeholder = "placeholder"
392
}
393

394
interface ChatMessageWithPlaceholders {
395
  type: "chatmessage" | "placeholder";
396
  role?: string;
397
  content?: string;
398
  name?: string;
399
}
400

401
type ChatMessageOrPlaceholder =
402
  | ChatMessage
403
  | { type: "placeholder"; name: string };
404

405
interface LangchainMessagesPlaceholder {
406
  variableName: string;
407
  optional?: boolean;
408
}
409

410
// Experiment types
411
type ExperimentItem<Input = any, ExpectedOutput = any, Metadata extends Record<string, any> = Record<string, any>> =
412
  | {
413
      input?: Input;
414
      expectedOutput?: ExpectedOutput;
415
      metadata?: Metadata;
416
    }
417
  | DatasetItem;
418

419
type ExperimentTaskParams<Input = any, ExpectedOutput = any, Metadata extends Record<string, any> = Record<string, any>> =
420
  ExperimentItem<Input, ExpectedOutput, Metadata>;
421

422
type ExperimentTask<Input = any, ExpectedOutput = any, Metadata extends Record<string, any> = Record<string, any>> = (
423
  params: ExperimentTaskParams<Input, ExpectedOutput, Metadata>
424
) => Promise<any>;
425

426
type Evaluation = Pick<ScoreBody, "name" | "value" | "comment" | "metadata" | "dataType">;
427

428
interface EvaluatorParams<Input = any, ExpectedOutput = any, Metadata extends Record<string, any> = Record<string, any>> {
429
  input: Input;
430
  output: any;
431
  expectedOutput?: ExpectedOutput;
432
  metadata?: Metadata;
433
}
434

435
type Evaluator<Input = any, ExpectedOutput = any, Metadata extends Record<string, any> = Record<string, any>> = (
436
  params: EvaluatorParams<Input, ExpectedOutput, Metadata>
437
) => Promise<Evaluation[] | Evaluation>;
438

439
interface RunEvaluatorParams<Input = any, ExpectedOutput = any, Metadata extends Record<string, any> = Record<string, any>> {
440
  itemResults: ExperimentItemResult<Input, ExpectedOutput, Metadata>[];
441
}
442

443
type RunEvaluator<Input = any, ExpectedOutput = any, Metadata extends Record<string, any> = Record<string, any>> = (
444
  params: RunEvaluatorParams<Input, ExpectedOutput, Metadata>
445
) => Promise<Evaluation[] | Evaluation>;
446

447
type ExperimentItemResult<Input = any, ExpectedOutput = any, Metadata extends Record<string, any> = Record<string, any>> = {
448
  item: ExperimentItem<Input, ExpectedOutput, Metadata>;
449
  output: any;
450
  evaluations: Evaluation[];
451
  traceId?: string;
452
  datasetRunId?: string;
453
};
454

455
// Media types
456
interface ParsedMediaReference {
457
  mediaId: string;
458
  source: string;
459
  contentType: string;
460
}
461
```
462

463
## Environment Variables
464

465
The client supports configuration via environment variables:
466

467
- `LANGFUSE_PUBLIC_KEY`: Public API key
468
- `LANGFUSE_SECRET_KEY`: Secret API key
469
- `LANGFUSE_BASE_URL` (or `LANGFUSE_BASEURL`): Langfuse instance URL
470
- `LANGFUSE_TIMEOUT`: Request timeout in seconds
471
- `LANGFUSE_FLUSH_AT`: Number of scores to batch before flushing (default: 10)
472
- `LANGFUSE_FLUSH_INTERVAL`: Flush interval in seconds (default: 1)
473
- `LANGFUSE_TRACING_ENVIRONMENT`: Default environment tag for traces
474

475
## OpenTelemetry Integration
476

477
This package integrates with OpenTelemetry for distributed tracing. Score methods accept OpenTelemetry `Span` objects to automatically link scores to traces and observations. The experiment framework uses OpenTelemetry for automatic tracing of task executions.
478

479
```typescript
480
import { Span } from '@opentelemetry/api';
481

482
// Link dataset item to a span
483
await datasetItem.link({ otelSpan: span }, 'experiment-run-1');
484

485
// Score an observation using its span
486
langfuse.score.observation({ otelSpan: span }, {
487
  name: 'accuracy',
488
  value: 0.95
489
});
490
```
491

492
## Error Handling
493

494
Methods that fetch data (like `prompt.get()`, `dataset.get()`) support fallback mechanisms:
495

496
```typescript
497
// Prompt with fallback
498
const prompt = await langfuse.prompt.get('my-prompt', {
499
  type: 'text',
500
  fallback: 'Default prompt text: {{variable}}'
501
});
502

503
// If fetch fails, fallback content is used
504
// prompt.isFallback will be true
505
```
506

507
Experiment evaluators handle failures gracefully - failed evaluators are logged but don't stop the experiment:
508

509
```typescript
510
const result = await langfuse.experiment.run({
511
  name: 'Test',
512
  data: items,
513
  task: myTask,
514
  evaluators: [
515
    goodEvaluator,      // Works fine
516
    brokenEvaluator,    // Fails but logged
517
    anotherEvaluator    // Still runs
518
  ]
519
});
520
// result.itemResults contains evaluations from successful evaluators
521
```
522

523
## Lifecycle Management
524

525
Always flush pending data before application exit:
526

527
```typescript
528
// Option 1: Manual flush
529
await langfuse.flush();
530

531
// Option 2: Graceful shutdown (flushes all managers)
532
await langfuse.shutdown();
533
```
534

535
Scores are batched automatically but can be flushed manually:
536

537
```typescript
538
langfuse.score.create({ name: 'quality', value: 0.8, traceId: 'abc' });
539
langfuse.score.create({ name: 'latency', value: 120, traceId: 'abc' });
540

541
// Force immediate send
542
await langfuse.score.flush();
543
```
544

545
## Deprecated APIs
546

547
The package maintains v3 compatibility with deprecated methods:
548

549
- `getPrompt()` → Use `prompt.get()`
550
- `createPrompt()` → Use `prompt.create()`
551
- `updatePrompt()` → Use `prompt.update()`
552
- `getDataset()` → Use `dataset.get()`
553
- `fetchTrace()` → Use `api.trace.get()`
554
- `fetchTraces()` → Use `api.trace.list()`
555
- `fetchObservation()` → Use `api.observations.get()`
556
- `fetchObservations()` → Use `api.observations.getMany()`
557
- `fetchSessions()` → Use `api.sessions.get()`
558
- `getDatasetRun()` → Use `api.datasets.getRun()`
559
- `getDatasetRuns()` → Use `api.datasets.getRuns()`
560
- `createDataset()` → Use `api.datasets.create()`
561
- `getDatasetItem()` → Use `api.datasetItems.get()`
562
- `createDatasetItem()` → Use `api.datasetItems.create()`
563
- `fetchMedia()` → Use `api.media.get()`
564
- `resolveMediaReferences()` → Use `media.resolveReferences()`
565

566
All deprecated methods are maintained for backward compatibility but the new manager-based API is recommended for new code.
567