0
# Client Configuration
1

2
The Langfuse Java client provides flexible configuration options through a builder pattern, allowing customization of API endpoints, authentication, headers, timeouts, and HTTP client settings.
3

4
## Capabilities
5

6
### LangfuseClient
7

8
The main entry point for the Langfuse API client. Provides access to all resource-specific clients.
9

10
```java { .api }
11
/**
12
 * Main Langfuse API client
13
 * Provides access to all resource clients
14
 */
15
public class LangfuseClient {
16
    // Resource client accessors
17
    AnnotationQueuesClient annotationQueues();
18
    CommentsClient comments();
19
    DatasetItemsClient datasetItems();
20
    DatasetRunItemsClient datasetRunItems();
21
    DatasetsClient datasets();
22
    HealthClient health();
23
    IngestionClient ingestion();
24
    MediaClient media();
25
    MetricsClient metrics();
26
    ModelsClient models();
27
    ObservationsClient observations();
28
    OrganizationsClient organizations();
29
    ProjectsClient projects();
30
    PromptVersionClient promptVersion();
31
    PromptsClient prompts();
32
    ScimClient scim();
33
    ScoreConfigsClient scoreConfigs();
34
    ScoreV2Client scoreV2();
35
    ScoreClient score();
36
    SessionsClient sessions();
37
    TraceClient trace();
38

39
    // Builder factory
40
    static LangfuseClientBuilder builder();
41
}
42
```
43

44
**Usage Example:**
45

46
```java
47
import com.langfuse.client.LangfuseClient;
48

49
// Create client
50
LangfuseClient client = LangfuseClient.builder()
51
    .url("https://cloud.langfuse.com")
52
    .credentials("pk-lf-...", "sk-lf-...")
53
    .build();
54

55
// Access resource clients
56
var prompts = client.prompts().list();
57
var traces = client.trace().list();
58
var health = client.health().health();
59
```
60

61
### LangfuseClientBuilder
62

63
Builder for creating and configuring LangfuseClient instances.
64

65
```java { .api }
66
/**
67
 * Builder for LangfuseClient with configuration options
68
 */
69
public class LangfuseClientBuilder {
70
    /**
71
     * Set authentication credentials (Basic Auth)
72
     * @param username Public key (pk-lf-...)
73
     * @param password Secret key (sk-lf-...)
74
     */
75
    LangfuseClientBuilder credentials(String username, String password);
76

77
    /**
78
     * Set custom API URL
79
     * @param url Base URL for Langfuse API
80
     *            - https://cloud.langfuse.com (EU)
81
     *            - https://us.cloud.langfuse.com (US)
82
     *            - http://localhost:3000 (local)
83
     */
84
    LangfuseClientBuilder url(String url);
85

86
    /**
87
     * Set X-Langfuse-Sdk-Name header
88
     * @param xLangfuseSdkName SDK name identifier
89
     */
90
    LangfuseClientBuilder xLangfuseSdkName(String xLangfuseSdkName);
91

92
    /**
93
     * Set X-Langfuse-Sdk-Version header
94
     * @param xLangfuseSdkVersion SDK version identifier
95
     */
96
    LangfuseClientBuilder xLangfuseSdkVersion(String xLangfuseSdkVersion);
97

98
    /**
99
     * Set X-Langfuse-Public-Key header
100
     * @param xLangfusePublicKey Public key for identification
101
     */
102
    LangfuseClientBuilder xLangfusePublicKey(String xLangfusePublicKey);
103

104
    /**
105
     * Set request timeout
106
     * @param timeout Timeout in seconds (default: 60)
107
     */
108
    LangfuseClientBuilder timeout(int timeout);
109

110
    /**
111
     * Set custom OkHttpClient
112
     * @param httpClient Configured OkHttpClient instance
113
     */
114
    LangfuseClientBuilder httpClient(OkHttpClient httpClient);
115

116
    /**
117
     * Build the configured LangfuseClient
118
     */
119
    LangfuseClient build();
120
}
121
```
122

123
**Usage Examples:**
124

125
```java
126
import com.langfuse.client.LangfuseClient;
127
import okhttp3.OkHttpClient;
128
import java.util.concurrent.TimeUnit;
129

130
// Basic configuration
131
LangfuseClient client = LangfuseClient.builder()
132
    .url("https://cloud.langfuse.com")
133
    .credentials("pk-lf-...", "sk-lf-...")
134
    .build();
135

136
// With custom timeout
137
LangfuseClient client = LangfuseClient.builder()
138
    .url("https://us.cloud.langfuse.com")
139
    .credentials("pk-lf-...", "sk-lf-...")
140
    .timeout(120)  // 2 minutes
141
    .build();
142

143
// With custom headers
144
LangfuseClient client = LangfuseClient.builder()
145
    .url("https://cloud.langfuse.com")
146
    .credentials("pk-lf-...", "sk-lf-...")
147
    .xLangfuseSdkName("my-app")
148
    .xLangfuseSdkVersion("1.0.0")
149
    .xLangfusePublicKey("pk-lf-...")
150
    .build();
151

152
// With custom HTTP client
153
OkHttpClient customHttpClient = new OkHttpClient.Builder()
154
    .connectTimeout(30, TimeUnit.SECONDS)
155
    .readTimeout(60, TimeUnit.SECONDS)
156
    .build();
157

158
LangfuseClient client = LangfuseClient.builder()
159
    .url("https://cloud.langfuse.com")
160
    .credentials("pk-lf-...", "sk-lf-...")
161
    .httpClient(customHttpClient)
162
    .build();
163
```
164

165
### ClientOptions
166

167
Encapsulates client-level configuration including environment, headers, and HTTP client settings.
168

169
```java { .api }
170
/**
171
 * Client-level configuration options
172
 */
173
public class ClientOptions {
174
    /**
175
     * Get the configured environment
176
     */
177
    Environment environment();
178

179
    /**
180
     * Get headers with optional request-specific overrides
181
     * @param requestOptions Per-request overrides (optional)
182
     */
183
    Map<String, String> headers(RequestOptions requestOptions);
184

185
    /**
186
     * Get the configured HTTP client
187
     */
188
    OkHttpClient httpClient();
189

190
    /**
191
     * Get HTTP client with custom timeout from request options
192
     * @param requestOptions Per-request overrides (optional)
193
     */
194
    OkHttpClient httpClientWithTimeout(RequestOptions requestOptions);
195

196
    /**
197
     * Create a new builder
198
     */
199
    static Builder builder();
200
}
201
```
202

203
**ClientOptions.Builder:**
204

205
```java { .api }
206
/**
207
 * Builder for ClientOptions
208
 */
209
public static class Builder {
210
    /**
211
     * Set the API environment
212
     * @param environment Environment with base URL
213
     */
214
    Builder environment(Environment environment);
215

216
    /**
217
     * Add a static header
218
     * @param key Header name
219
     * @param value Header value
220
     */
221
    Builder addHeader(String key, String value);
222

223
    /**
224
     * Add a dynamic header (computed at request time)
225
     * @param key Header name
226
     * @param value Supplier for header value
227
     */
228
    Builder addHeader(String key, Supplier<String> value);
229

230
    /**
231
     * Set timeout in seconds
232
     * @param timeout Timeout value (default: 60)
233
     */
234
    Builder timeout(int timeout);
235

236
    /**
237
     * Set custom HTTP client
238
     * @param httpClient Configured OkHttpClient
239
     */
240
    Builder httpClient(OkHttpClient httpClient);
241

242
    /**
243
     * Build the ClientOptions
244
     */
245
    ClientOptions build();
246
}
247
```
248

249
**Usage Example:**
250

251
```java
252
import com.langfuse.client.core.ClientOptions;
253
import com.langfuse.client.core.Environment;
254

255
ClientOptions options = ClientOptions.builder()
256
    .environment(Environment.custom("https://cloud.langfuse.com"))
257
    .addHeader("X-Custom-Header", "value")
258
    .addHeader("X-Dynamic-Header", () -> String.valueOf(System.currentTimeMillis()))
259
    .timeout(90)
260
    .build();
261
```
262

263
### RequestOptions
264

265
Per-request configuration for overriding client-level settings.
266

267
```java { .api }
268
/**
269
 * Per-request configuration options
270
 */
271
public class RequestOptions {
272
    /**
273
     * Get optional timeout value
274
     */
275
    Optional<Integer> getTimeout();
276

277
    /**
278
     * Get timeout time unit
279
     */
280
    TimeUnit getTimeoutTimeUnit();
281

282
    /**
283
     * Get request-specific headers
284
     */
285
    Map<String, String> getHeaders();
286

287
    /**
288
     * Create a new builder
289
     */
290
    static Builder builder();
291
}
292
```
293

294
**RequestOptions.Builder:**
295

296
```java { .api }
297
/**
298
 * Builder for RequestOptions
299
 */
300
public static class Builder {
301
    /**
302
     * Set X-Langfuse-Sdk-Name header
303
     */
304
    Builder xLangfuseSdkName(String xLangfuseSdkName);
305

306
    /**
307
     * Set X-Langfuse-Sdk-Version header
308
     */
309
    Builder xLangfuseSdkVersion(String xLangfuseSdkVersion);
310

311
    /**
312
     * Set X-Langfuse-Public-Key header
313
     */
314
    Builder xLangfusePublicKey(String xLangfusePublicKey);
315

316
    /**
317
     * Set timeout value (milliseconds by default)
318
     * @param timeout Timeout value
319
     */
320
    Builder timeout(Integer timeout);
321

322
    /**
323
     * Set timeout with custom time unit
324
     * @param timeout Timeout value
325
     * @param timeoutTimeUnit Time unit for timeout
326
     */
327
    Builder timeout(Integer timeout, TimeUnit timeoutTimeUnit);
328

329
    /**
330
     * Add a static header
331
     * @param key Header name
332
     * @param value Header value
333
     */
334
    Builder addHeader(String key, String value);
335

336
    /**
337
     * Add a dynamic header
338
     * @param key Header name
339
     * @param value Supplier for header value
340
     */
341
    Builder addHeader(String key, Supplier<String> value);
342

343
    /**
344
     * Build the RequestOptions
345
     */
346
    RequestOptions build();
347
}
348
```
349

350
**Usage Example:**
351

352
```java
353
import com.langfuse.client.core.RequestOptions;
354
import java.util.concurrent.TimeUnit;
355

356
// Override timeout for a single request
357
RequestOptions options = RequestOptions.builder()
358
    .timeout(5, TimeUnit.MINUTES)
359
    .build();
360

361
var prompts = client.prompts().list(request, options);
362

363
// Add custom headers for a single request
364
RequestOptions options = RequestOptions.builder()
365
    .addHeader("X-Request-ID", "unique-request-id")
366
    .xLangfusePublicKey("pk-lf-...")
367
    .build();
368

369
var trace = client.trace().get(traceId, options);
370
```
371

372
### Environment
373

374
Represents the API environment and base URL.
375

376
```java { .api }
377
/**
378
 * API environment configuration
379
 */
380
public class Environment {
381
    /**
382
     * Get the base URL
383
     */
384
    String getUrl();
385

386
    /**
387
     * Create a custom environment with specified URL
388
     * @param url Base URL for API
389
     */
390
    static Environment custom(String url);
391
}
392
```
393

394
**Usage Example:**
395

396
```java
397
import com.langfuse.client.core.Environment;
398

399
// Create custom environment
400
Environment euEnv = Environment.custom("https://cloud.langfuse.com");
401
Environment usEnv = Environment.custom("https://us.cloud.langfuse.com");
402
Environment localEnv = Environment.custom("http://localhost:3000");
403
```
404

405
## Configuration Patterns
406

407
### Environment-Specific Clients
408

409
```java
410
// EU Region
411
LangfuseClient euClient = LangfuseClient.builder()
412
    .url("https://cloud.langfuse.com")
413
    .credentials("pk-lf-...", "sk-lf-...")
414
    .build();
415

416
// US Region
417
LangfuseClient usClient = LangfuseClient.builder()
418
    .url("https://us.cloud.langfuse.com")
419
    .credentials("pk-lf-...", "sk-lf-...")
420
    .build();
421

422
// Local Development
423
LangfuseClient localClient = LangfuseClient.builder()
424
    .url("http://localhost:3000")
425
    .credentials("pk-lf-...", "sk-lf-...")
426
    .build();
427
```
428

429
### Per-Request Customization
430

431
```java
432
// Client with default 60s timeout
433
LangfuseClient client = LangfuseClient.builder()
434
    .url("https://cloud.langfuse.com")
435
    .credentials("pk-lf-...", "sk-lf-...")
436
    .build();
437

438
// Override timeout for specific long-running request
439
RequestOptions longTimeout = RequestOptions.builder()
440
    .timeout(5, TimeUnit.MINUTES)
441
    .build();
442

443
var result = client.ingestion().batch(largeRequest, longTimeout);
444

445
// Add custom tracking headers
446
RequestOptions trackingOptions = RequestOptions.builder()
447
    .addHeader("X-Request-ID", requestId)
448
    .addHeader("X-User-ID", userId)
449
    .build();
450

451
var trace = client.trace().get(traceId, trackingOptions);
452
```
453

454
### Custom HTTP Client Configuration
455

456
```java
457
import okhttp3.OkHttpClient;
458
import okhttp3.logging.HttpLoggingInterceptor;
459
import java.util.concurrent.TimeUnit;
460

461
// Configure HTTP client with logging and custom timeouts
462
HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
463
logging.setLevel(HttpLoggingInterceptor.Level.BODY);
464

465
OkHttpClient httpClient = new OkHttpClient.Builder()
466
    .connectTimeout(30, TimeUnit.SECONDS)
467
    .readTimeout(90, TimeUnit.SECONDS)
468
    .writeTimeout(90, TimeUnit.SECONDS)
469
    .addInterceptor(logging)
470
    .build();
471

472
LangfuseClient client = LangfuseClient.builder()
473
    .url("https://cloud.langfuse.com")
474
    .credentials("pk-lf-...", "sk-lf-...")
475
    .httpClient(httpClient)
476
    .build();
477
```
478

479
## Authentication
480

481
The client uses HTTP Basic Authentication with your Langfuse API credentials:
482

483
- **Username**: Public key (format: `pk-lf-...`)
484
- **Password**: Secret key (format: `sk-lf-...`)
485

486
```java
487
LangfuseClient client = LangfuseClient.builder()
488
    .url("https://cloud.langfuse.com")
489
    .credentials("pk-lf-1234567890abcdef", "sk-lf-fedcba0987654321")
490
    .build();
491
```
492

493
Some operations require an organization-scoped API key:
494
- Project creation and deletion
495
- API key management
496
- Organization and project membership management
497
- SCIM user provisioning
498

499
## Related Documentation
500

501
- [Exceptions](./exceptions.md) - Error handling and exception types
502