0
# API Client and Core Concepts
1

2
The LangfuseAPIClient is the main entry point for interacting with the Langfuse observability platform. It provides type-safe access to 23 resource clients, authentication management, retry logic, and comprehensive error handling.
3

4
## Capabilities
5

6
### LangfuseAPIClient Class
7

8
Main API client providing lazy-loaded access to all Langfuse platform resources.
9

10
```typescript { .api }
11
class LangfuseAPIClient {
12
  constructor(options: LangfuseAPIClient.Options);
13

14
  // Resource accessors (read-only getters)
15
  readonly annotationQueues: AnnotationQueues;
16
  readonly blobStorageIntegrations: BlobStorageIntegrations;
17
  readonly comments: Comments;
18
  readonly datasetItems: DatasetItems;
19
  readonly datasetRunItems: DatasetRunItems;
20
  readonly datasets: Datasets;
21
  readonly health: Health;
22
  readonly ingestion: Ingestion;
23
  readonly llmConnections: LlmConnections;
24
  readonly media: Media;
25
  readonly metrics: Metrics;
26
  readonly models: Models;
27
  readonly observations: Observations;
28
  readonly organizations: Organizations;
29
  readonly projects: Projects;
30
  readonly promptVersion: PromptVersion;
31
  readonly prompts: Prompts;
32
  readonly scim: Scim;
33
  readonly scoreConfigs: ScoreConfigs;
34
  readonly scoreV2: ScoreV2;
35
  readonly score: Score;
36
  readonly sessions: Sessions;
37
  readonly trace: Trace;
38
}
39
```
40

41
**Import:**
42

43
```typescript
44
import { LangfuseAPIClient } from '@langfuse/core';
45
```
46

47
#### Constructor
48

49
Creates a new API client instance with authentication and configuration.
50

51
```typescript { .api }
52
constructor(options: LangfuseAPIClient.Options)
53

54
interface Options {
55
  environment: core.Supplier<string>;
56
  baseUrl?: core.Supplier<string>;
57
  username?: core.Supplier<string | undefined>;
58
  password?: core.Supplier<string | undefined>;
59
  xLangfuseSdkName?: core.Supplier<string | undefined>;
60
  xLangfuseSdkVersion?: core.Supplier<string | undefined>;
61
  xLangfusePublicKey?: core.Supplier<string | undefined>;
62
  headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
63
}
64

65
type Supplier<T> = T | (() => T);
66
```
67

68
**Parameters:**
69
- `options.environment` - Base API URL (e.g., 'https://cloud.langfuse.com')
70
- `options.baseUrl` - Alternative to environment for specifying base URL
71
- `options.username` - Public API key (used as Basic Auth username)
72
- `options.password` - Secret API key (used as Basic Auth password)
73
- `options.xLangfuseSdkName` - SDK identifier (e.g., 'javascript')
74
- `options.xLangfuseSdkVersion` - SDK version (e.g., '4.2.0')
75
- `options.xLangfusePublicKey` - Public key for request headers
76
- `options.headers` - Additional custom headers for all requests
77

78
**Usage Example:**
79

80
```typescript
81
import { LangfuseAPIClient, LANGFUSE_SDK_NAME, LANGFUSE_SDK_VERSION } from '@langfuse/core';
82

83
// Basic initialization
84
const client = new LangfuseAPIClient({
85
  environment: 'https://cloud.langfuse.com',
86
  username: 'pk-lf-...',
87
  password: 'sk-lf-...'
88
});
89

90
// With all options
91
const client = new LangfuseAPIClient({
92
  environment: 'https://cloud.langfuse.com',
93
  username: process.env.LANGFUSE_PUBLIC_KEY,
94
  password: process.env.LANGFUSE_SECRET_KEY,
95
  xLangfuseSdkName: LANGFUSE_SDK_NAME,
96
  xLangfuseSdkVersion: LANGFUSE_SDK_VERSION,
97
  xLangfusePublicKey: process.env.LANGFUSE_PUBLIC_KEY,
98
  headers: {
99
    'User-Agent': 'my-app/1.0.0'
100
  }
101
});
102

103
// Access resources
104
const trace = await client.trace.get('trace-id');
105
const prompts = await client.prompts.list();
106
```
107

108
#### Resource Accessors
109

110
The client exposes 23 resource clients as read-only properties. These are lazily instantiated on first access.
111

112
**Core Observability Resources:**
113

114
```typescript
115
// Traces - Complete trace lifecycle management
116
client.trace.get(traceId);
117
client.trace.list(filters);
118
client.trace.delete(traceId);
119

120
// Observations - Detailed observation queries
121
client.observations.list(filters);
122

123
// Sessions - Session grouping and analytics
124
client.sessions.list(filters);
125
```
126

127
**Prompt Management Resources:**
128

129
```typescript
130
// Prompts - Version-controlled prompt templates
131
client.prompts.get(name, { version, label });
132
client.prompts.list(filters);
133
client.prompts.create(request);
134

135
// Prompt Versions - Update labels for specific version
136
client.promptVersion.update(promptName, version, { newLabels: ['production'] });
137
```
138

139
**Evaluation Resources:**
140

141
```typescript
142
// Datasets - Test dataset management
143
client.datasets.list();
144
client.datasets.create(request);
145

146
// Dataset Items - Individual entries
147
client.datasetItems.create(request);
148

149
// Dataset Runs - Evaluation tracking
150
client.datasets.getRuns(datasetId);
151

152
// Scores - Score creation and queries
153
client.score.create(request);
154
client.scoreV2.list(filters);
155
client.scoreConfigs.list();
156
```
157

158
**Platform Management Resources:**
159

160
```typescript
161
// Projects - Project administration
162
client.projects.list();
163

164
// Organizations - Multi-tenant management
165
client.organizations.list();
166

167
// Models - Model configuration
168
client.models.list();
169
client.models.create(request);
170

171
// Media - Media upload and retrieval
172
client.media.get(mediaId);
173
client.media.upload(request);
174
```
175

176
**Additional Resources:**
177

178
```typescript
179
// Health - Health check endpoint
180
client.health.health();
181

182
// Metrics - Analytics and metrics
183
client.metrics.get(filters);
184

185
// Comments - Comment management
186
client.comments.create(request);
187
client.comments.list(filters);
188

189
// Annotation Queues - Annotation workflow
190
client.annotationQueues.list();
191
client.annotationQueues.create(request);
192

193
// LLM Connections - LLM integration management
194
client.llmConnections.list();
195

196
// Blob Storage Integrations - Storage configuration
197
client.blobStorageIntegrations.list();
198

199
// SCIM - Identity management
200
client.scim.getServiceProviderConfig();
201

202
// Ingestion - Legacy batch ingestion (deprecated)
203
client.ingestion.batch(request);
204
```
205

206
### Request Options
207

208
All resource methods accept optional request options for customizing behavior.
209

210
```typescript { .api }
211
interface RequestOptions {
212
  timeoutInSeconds?: number;
213
  maxRetries?: number;
214
  abortSignal?: AbortSignal;
215
  xLangfuseSdkName?: string | undefined;
216
  xLangfuseSdkVersion?: string | undefined;
217
  xLangfusePublicKey?: string | undefined;
218
  queryParams?: Record<string, unknown>;
219
  headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
220
}
221
```
222

223
**Parameters:**
224
- `timeoutInSeconds` - Request timeout (default: 60 seconds)
225
- `maxRetries` - Maximum retry attempts (default: 2)
226
- `abortSignal` - AbortSignal for request cancellation
227
- `xLangfuseSdkName` - Override SDK name for this request
228
- `xLangfuseSdkVersion` - Override SDK version for this request
229
- `xLangfusePublicKey` - Override public key for this request
230
- `queryParams` - Additional query parameters
231
- `headers` - Additional headers for this request
232

233
**Usage Example:**
234

235
```typescript
236
// Custom timeout and retries
237
const trace = await client.trace.get('trace-id', {
238
  timeoutInSeconds: 30,
239
  maxRetries: 5
240
});
241

242
// Request cancellation
243
const controller = new AbortController();
244
const promise = client.trace.list({ page: 1 }, {
245
  abortSignal: controller.signal
246
});
247

248
// Cancel if needed
249
setTimeout(() => controller.abort(), 5000);
250

251
// Custom headers
252
const prompts = await client.prompts.list({}, {
253
  headers: {
254
    'X-Custom-Header': 'value'
255
  }
256
});
257
```
258

259
## Core Concepts
260

261
### Authentication
262

263
The client uses HTTP Basic Authentication with your Langfuse API keys:
264
- **Username**: Public API key (starts with `pk-lf-`)
265
- **Password**: Secret API key (starts with `sk-lf-`)
266

267
```typescript
268
const client = new LangfuseAPIClient({
269
  environment: 'https://cloud.langfuse.com',
270
  username: 'pk-lf-your-public-key',
271
  password: 'sk-lf-your-secret-key'
272
});
273
```
274

275
**Best Practice**: Always use environment variables for API keys:
276

277
```typescript
278
import { getEnv } from '@langfuse/core';
279

280
const client = new LangfuseAPIClient({
281
  environment: getEnv('LANGFUSE_BASE_URL') || 'https://cloud.langfuse.com',
282
  username: getEnv('LANGFUSE_PUBLIC_KEY'),
283
  password: getEnv('LANGFUSE_SECRET_KEY')
284
});
285
```
286

287
### Lazy Loading
288

289
Resource clients are created lazily on first access, improving performance and memory usage:
290

291
```typescript
292
const client = new LangfuseAPIClient(options);
293

294
// No resource clients created yet
295

296
const trace = await client.trace.get('id');
297
// Trace client created on first access
298

299
const prompt = await client.prompts.get('name');
300
// Prompts client created on first access
301
```
302

303
### Retry Logic
304

305
The client automatically retries failed requests with exponential backoff:
306
- **Default retries**: 2 attempts (3 total tries)
307
- **Retryable errors**: Network errors, 5xx server errors, 429 rate limiting
308
- **Non-retryable**: 4xx client errors (except 429)
309

310
```typescript
311
// Customize retry behavior
312
const result = await client.trace.get('trace-id', {
313
  maxRetries: 5,
314
  timeoutInSeconds: 30
315
});
316
```
317

318
### Error Handling
319

320
The client throws structured errors for different scenarios:
321

322
```typescript
323
import {
324
  LangfuseAPIClient,
325
  LangfuseAPIError,
326
  LangfuseAPITimeoutError
327
} from '@langfuse/core';
328

329
try {
330
  const trace = await client.trace.get('invalid-id');
331
} catch (error) {
332
  if (error instanceof LangfuseAPITimeoutError) {
333
    console.error('Request timed out');
334
  } else if (error instanceof LangfuseAPIError) {
335
    console.error('API error:', error.statusCode, error.body);
336
  } else {
337
    console.error('Unexpected error:', error);
338
  }
339
}
340
```
341

342
See [Error Handling](./errors.md) for detailed error documentation.
343

344
### Pagination
345

346
List operations support pagination with consistent parameters:
347

348
```typescript
349
// Paginated list
350
const traces = await client.trace.list({
351
  page: 1,        // Page number (starts at 1)
352
  limit: 50       // Items per page (default: 50)
353
});
354

355
// Response structure
356
interface PaginatedResponse<T> {
357
  data: T[];
358
  meta: {
359
    page: number;
360
    limit: number;
361
    totalItems: number;
362
    totalPages: number;
363
  };
364
}
365

366
// Iterate through pages
367
async function getAllTraces() {
368
  const allTraces = [];
369
  let page = 1;
370

371
  while (true) {
372
    const response = await client.trace.list({ page, limit: 100 });
373
    allTraces.push(...response.data);
374

375
    if (page >= response.meta.totalPages) break;
376
    page++;
377
  }
378

379
  return allTraces;
380
}
381
```
382

383
### Filtering and Sorting
384

385
Many list operations support filtering and sorting:
386

387
```typescript
388
// Filter traces
389
const traces = await client.trace.list({
390
  userId: 'user-123',
391
  sessionId: 'session-456',
392
  fromTimestamp: '2024-01-01T00:00:00Z',
393
  toTimestamp: '2024-12-31T23:59:59Z',
394
  tags: ['production', 'api'],
395
  name: 'chat-completion',
396
  orderBy: 'timestamp.desc'
397
});
398

399
// Filter prompts
400
const prompts = await client.prompts.list({
401
  name: 'chat-prompt',
402
  tag: 'production',
403
  label: 'latest',
404
  fromUpdatedAt: '2024-01-01T00:00:00Z'
405
});
406
```
407

408
### Field Selection
409

410
Optimize response payload by selecting specific field groups:
411

412
```typescript
413
// Get trace with specific fields
414
const trace = await client.trace.list({
415
  fields: 'core,scores,metrics'  // Exclude large fields like observations
416
});
417

418
// Available field groups:
419
// - core: Always included (id, name, timestamp, etc.)
420
// - io: Input/output data
421
// - scores: Associated scores
422
// - observations: Nested observations
423
// - metrics: Aggregated metrics
424
```
425

426
### Supplier Pattern
427

428
Configuration values can be static or dynamic using the Supplier pattern:
429

430
```typescript
431
type Supplier<T> = T | (() => T);
432

433
// Static value
434
const client1 = new LangfuseAPIClient({
435
  environment: 'https://cloud.langfuse.com',
436
  username: 'pk-lf-...'
437
});
438

439
// Dynamic value (evaluated on each request)
440
const client2 = new LangfuseAPIClient({
441
  environment: () => getCurrentEnvironmentUrl(),
442
  username: () => getRotatingApiKey(),
443
  headers: {
444
    'X-Request-Id': () => generateRequestId()
445
  }
446
});
447
```
448

449
## Usage Patterns
450

451
### Basic Client Setup
452

453
```typescript
454
import { LangfuseAPIClient } from '@langfuse/core';
455

456
const client = new LangfuseAPIClient({
457
  environment: 'https://cloud.langfuse.com',
458
  username: process.env.LANGFUSE_PUBLIC_KEY,
459
  password: process.env.LANGFUSE_SECRET_KEY
460
});
461

462
// Use the client
463
const trace = await client.trace.get('trace-id');
464
```
465

466
### Multi-Environment Setup
467

468
```typescript
469
import { LangfuseAPIClient } from '@langfuse/core';
470

471
class LangfuseService {
472
  private clients: Map<string, LangfuseAPIClient>;
473

474
  constructor() {
475
    this.clients = new Map([
476
      ['production', new LangfuseAPIClient({
477
        environment: 'https://cloud.langfuse.com',
478
        username: process.env.PROD_PUBLIC_KEY,
479
        password: process.env.PROD_SECRET_KEY
480
      })],
481
      ['staging', new LangfuseAPIClient({
482
        environment: 'https://staging.langfuse.com',
483
        username: process.env.STAGING_PUBLIC_KEY,
484
        password: process.env.STAGING_SECRET_KEY
485
      })]
486
    ]);
487
  }
488

489
  getClient(env: string): LangfuseAPIClient {
490
    return this.clients.get(env) || this.clients.get('production')!;
491
  }
492
}
493
```
494

495
### Request Cancellation
496

497
```typescript
498
import { LangfuseAPIClient } from '@langfuse/core';
499

500
async function fetchWithTimeout(
501
  client: LangfuseAPIClient,
502
  traceId: string,
503
  timeoutMs: number
504
) {
505
  const controller = new AbortController();
506
  const timeout = setTimeout(() => controller.abort(), timeoutMs);
507

508
  try {
509
    return await client.trace.get(traceId, {
510
      abortSignal: controller.signal
511
    });
512
  } finally {
513
    clearTimeout(timeout);
514
  }
515
}
516

517
// Use it
518
const trace = await fetchWithTimeout(client, 'trace-id', 5000);
519
```
520

521
### Error Recovery
522

523
```typescript
524
import {
525
  LangfuseAPIClient,
526
  LangfuseAPIError,
527
  LangfuseAPITimeoutError
528
} from '@langfuse/core';
529

530
async function fetchTraceWithRecovery(
531
  client: LangfuseAPIClient,
532
  traceId: string
533
) {
534
  try {
535
    return await client.trace.get(traceId, {
536
      maxRetries: 3,
537
      timeoutInSeconds: 30
538
    });
539
  } catch (error) {
540
    if (error instanceof LangfuseAPITimeoutError) {
541
      console.warn('Request timed out, using fallback');
542
      return null;
543
    }
544

545
    if (error instanceof LangfuseAPIError) {
546
      if (error.statusCode === 404) {
547
        console.warn('Trace not found');
548
        return null;
549
      }
550

551
      if (error.statusCode === 429) {
552
        console.warn('Rate limited, waiting before retry');
553
        await new Promise(resolve => setTimeout(resolve, 5000));
554
        return fetchTraceWithRecovery(client, traceId);
555
      }
556
    }
557

558
    throw error;
559
  }
560
}
561
```
562

563
## Type Definitions
564

565
```typescript { .api }
566
class LangfuseAPIClient {
567
  constructor(options: LangfuseAPIClient.Options);
568
  readonly annotationQueues: AnnotationQueues;
569
  readonly blobStorageIntegrations: BlobStorageIntegrations;
570
  readonly comments: Comments;
571
  readonly datasetItems: DatasetItems;
572
  readonly datasetRunItems: DatasetRunItems;
573
  readonly datasets: Datasets;
574
  readonly health: Health;
575
  readonly ingestion: Ingestion;
576
  readonly llmConnections: LlmConnections;
577
  readonly media: Media;
578
  readonly metrics: Metrics;
579
  readonly models: Models;
580
  readonly observations: Observations;
581
  readonly organizations: Organizations;
582
  readonly projects: Projects;
583
  readonly promptVersion: PromptVersion;
584
  readonly prompts: Prompts;
585
  readonly scim: Scim;
586
  readonly scoreConfigs: ScoreConfigs;
587
  readonly scoreV2: ScoreV2;
588
  readonly score: Score;
589
  readonly sessions: Sessions;
590
  readonly trace: Trace;
591
}
592

593
namespace LangfuseAPIClient {
594
  interface Options {
595
    environment: core.Supplier<string>;
596
    baseUrl?: core.Supplier<string>;
597
    username?: core.Supplier<string | undefined>;
598
    password?: core.Supplier<string | undefined>;
599
    xLangfuseSdkName?: core.Supplier<string | undefined>;
600
    xLangfuseSdkVersion?: core.Supplier<string | undefined>;
601
    xLangfusePublicKey?: core.Supplier<string | undefined>;
602
    headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
603
  }
604
}
605

606
interface RequestOptions {
607
  timeoutInSeconds?: number;
608
  maxRetries?: number;
609
  abortSignal?: AbortSignal;
610
  xLangfuseSdkName?: string | undefined;
611
  xLangfuseSdkVersion?: string | undefined;
612
  xLangfusePublicKey?: string | undefined;
613
  queryParams?: Record<string, unknown>;
614
  headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
615
}
616

617
type Supplier<T> = T | (() => T);
618
```
619

620
## Best Practices
621

622
1. **Environment Variables**: Always use environment variables for API keys, never hardcode them
623
2. **Singleton Client**: Create one client instance per environment and reuse it throughout your application
624
3. **Error Handling**: Always wrap API calls in try-catch blocks and handle specific error types
625
4. **Pagination**: Implement proper pagination for list operations to avoid memory issues
626
5. **Field Selection**: Use field selection to minimize response payload when full data isn't needed
627
6. **Timeout Configuration**: Set appropriate timeouts based on your use case (longer for batch operations)
628
7. **Retry Strategy**: Customize retry logic for critical operations vs. non-critical queries
629
8. **Request Cancellation**: Implement cancellation for user-triggered operations that may be abandoned
630
9. **Logging**: Use the SDK logger to track API interactions for debugging
631
10. **Type Safety**: Leverage TypeScript types for compile-time validation of requests
632