0
# Langfuse Java Client
1

2
Langfuse Java Client is an auto-generated Java API client for Langfuse, an open-source observability and analytics platform for LLM applications. This client enables Java developers to interact with the Langfuse API for managing traces, observations, prompts, datasets, scores, and other observability features. Built with Maven, it leverages Jackson for JSON serialization and OkHttp for HTTP communication.
3

4
## Package Information
5

6
- **Package Name**: langfuse-java
7
- **Group ID**: com.langfuse
8
- **Artifact ID**: langfuse-java
9
- **Package Type**: maven
10
- **Language**: Java
11
- **Installation**: Add dependency to `pom.xml`:
12

13
```xml
14
<dependency>
15
    <groupId>com.langfuse</groupId>
16
    <artifactId>langfuse-java</artifactId>
17
    <version>0.1.0</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import com.langfuse.client.LangfuseClient;
25
import com.langfuse.client.core.LangfuseClientApiException;
26
```
27

28
For specific functionality, import the relevant types:
29

30
```java
31
// Prompts
32
import com.langfuse.client.resources.prompts.types.*;
33

34
// Traces and observations
35
import com.langfuse.client.resources.trace.types.*;
36
import com.langfuse.client.resources.observations.types.*;
37

38
// Ingestion (primary tracing API)
39
import com.langfuse.client.resources.ingestion.types.*;
40

41
// Common types
42
import com.langfuse.client.resources.commons.types.*;
43
```
44

45
## Basic Usage
46

47
```java
48
import com.langfuse.client.LangfuseClient;
49
import com.langfuse.client.core.LangfuseClientApiException;
50
import com.langfuse.client.resources.prompts.types.PromptMetaListResponse;
51

52
public class LangfuseExample {
53
    public static void main(String[] args) {
54
        // Initialize client with credentials
55
        LangfuseClient client = LangfuseClient.builder()
56
            .url("https://cloud.langfuse.com")  // EU data region
57
            // .url("https://us.cloud.langfuse.com")  // US data region
58
            // .url("http://localhost:3000")  // Local deployment
59
            .credentials("pk-lf-...", "sk-lf-...")
60
            .build();
61

62
        // Make API requests
63
        try {
64
            PromptMetaListResponse prompts = client.prompts().list();
65
            System.out.println("Prompts: " + prompts);
66
        } catch (LangfuseClientApiException error) {
67
            System.err.println("Error: " + error.statusCode());
68
            System.err.println("Body: " + error.body());
69
        }
70
    }
71
}
72
```
73

74
## Architecture
75

76
The Langfuse Java client is organized around several key components:
77

78
### Main Client
79

80
- **LangfuseClient**: Entry point providing access to all resource-specific clients
81
- **LangfuseClientBuilder**: Builder pattern for configuring client instances with custom URLs, credentials, headers, and HTTP settings
82

83
### Resource Clients
84

85
The client provides access to 21 specialized resource clients, each managing a specific area of the Langfuse API:
86

87
- **Tracing**: IngestionClient (batch tracing), TraceClient, ObservationsClient, SessionsClient
88
- **Prompts**: PromptsClient, PromptVersionClient
89
- **Datasets**: DatasetsClient, DatasetItemsClient, DatasetRunItemsClient
90
- **Scoring**: ScoreClient, ScoreV2Client, ScoreConfigsClient
91
- **Models**: ModelsClient
92
- **Metrics**: MetricsClient
93
- **Comments & Annotations**: CommentsClient, AnnotationQueuesClient
94
- **Organization Management**: ProjectsClient, OrganizationsClient, ScimClient
95
- **Media**: MediaClient
96
- **Health**: HealthClient
97

98
### Type System
99

100
- **Request Types**: Builder-based request objects with staged builders for required fields
101
- **Response Types**: Immutable response objects with getters
102
- **Common Types**: Shared domain objects (Trace, Observation, Score, Dataset, etc.)
103
- **Union Types**: Type-safe polymorphic data (Score variants, Prompt variants, Event types)
104
- **Enums**: Type-safe constants for status values, data types, and configuration options
105

106
### Error Handling
107

108
- **LangfuseClientException**: Base exception for SDK errors
109
- **LangfuseClientApiException**: Exception for non-2XX responses with status code and body
110
- **Specific Errors**: UnauthorizedError, AccessDeniedError, NotFoundError, etc.
111

112
### Configuration
113

114
- **ClientOptions**: Client-level configuration (environment, headers, HTTP client, timeout)
115
- **RequestOptions**: Per-request overrides for headers and timeout
116
- **Environment**: Configurable API base URL (cloud EU, cloud US, or custom)
117

118
## Capabilities
119

120
### Client Configuration
121

122
Configure the LangfuseClient with credentials, custom URLs, headers, and HTTP settings.
123

124
```java { .api }
125
// Builder interface
126
public static LangfuseClientBuilder builder();
127

128
// Build configured client
129
public LangfuseClient build();
130
```
131

132
[Client Configuration](./client-configuration.md)
133

134
### Tracing via Ingestion API
135

136
Batch ingestion of tracing events including traces, observations (spans, events, generations), and scores. This is the primary API for tracing operations, supporting event deduplication and multiple event types in a single batch.
137

138
```java { .api }
139
/**
140
 * Batch ingestion for Langfuse tracing
141
 * Supports event deduplication, handles multiple event types
142
 * Batch sizes limited to 3.5 MB
143
 * Returns 207 status with error details instead of 4xx for input errors
144
 */
145
IngestionResponse batch(IngestionRequest request);
146
IngestionResponse batch(IngestionRequest request, RequestOptions requestOptions);
147
```
148

149
[Ingestion API](./ingestion.md)
150

151
### Trace Management
152

153
Retrieve and delete traces with filtering and pagination.
154

155
```java { .api }
156
// Get a specific trace with full details
157
TraceWithFullDetails get(String traceId);
158

159
// List traces with filters
160
Traces list();
161
Traces list(GetTracesRequest request);
162

163
// Delete trace(s)
164
DeleteTraceResponse delete(String traceId);
165
DeleteTraceResponse deleteMultiple(DeleteTracesRequest request);
166
```
167

168
[Traces and Observations](./traces-observations.md)
169

170
### Observation Management
171

172
Retrieve observations (spans, events, generations) with extensive filtering options.
173

174
```java { .api }
175
// Get a specific observation
176
ObservationsView get(String observationId);
177

178
// List observations with filters
179
ObservationsViews getMany();
180
ObservationsViews getMany(GetObservationsRequest request);
181
```
182

183
[Traces and Observations](./traces-observations.md)
184

185
### Prompt Management
186

187
Manage prompt templates in text and chat formats with versioning and labels.
188

189
```java { .api }
190
// Get prompt by name with optional version/label
191
Prompt get(String promptName);
192
Prompt get(String promptName, GetPromptRequest request);
193

194
// List all prompts with metadata
195
PromptMetaListResponse list();
196

197
// Create new prompt version
198
Prompt create(CreatePromptRequest request);
199
```
200

201
[Prompts](./prompts.md)
202

203
### Dataset Management
204

205
Create and manage datasets for evaluation, including dataset items and runs.
206

207
```java { .api }
208
// List datasets
209
PaginatedDatasets list();
210

211
// Get dataset
212
Dataset get(String datasetName);
213

214
// Create dataset
215
Dataset create(CreateDatasetRequest request);
216

217
// Get dataset run with items
218
DatasetRunWithItems getRun(String datasetName, String runName);
219
```
220

221
[Datasets](./datasets.md)
222

223
### Score Management
224

225
Create, retrieve, and configure scores for traces and observations.
226

227
```java { .api }
228
// Create score
229
CreateScoreResponse create(CreateScoreRequest request);
230

231
// Get scores with extensive filtering (v2 API)
232
GetScoresResponse get();
233
GetScoresResponse get(GetScoresRequest request);
234

235
// Delete score
236
void delete(String scoreId);
237
```
238

239
[Scores](./scores.md)
240

241
### Session Management
242

243
Retrieve sessions and their associated traces.
244

245
```java { .api }
246
// List sessions
247
PaginatedSessions list();
248
PaginatedSessions list(GetSessionsRequest request);
249

250
// Get session with all traces
251
SessionWithTraces get(String sessionId);
252
```
253

254
[Sessions](./sessions.md)
255

256
### Model Management
257

258
Manage LLM model definitions and pricing configurations.
259

260
```java { .api }
261
// Create model
262
Model create(CreateModelRequest request);
263

264
// List models
265
PaginatedModels list();
266

267
// Get model
268
Model get(String id);
269

270
// Delete model
271
void delete(String id);
272
```
273

274
[Models](./models.md)
275

276
### Metrics
277

278
Query project metrics using a JSON query object.
279

280
```java { .api }
281
MetricsResponse metrics(GetMetricsRequest request);
282
```
283

284
[Metrics](./metrics.md)
285

286
### Comments and Annotations
287

288
Manage comments on traces, observations, sessions, and prompts. Manage annotation queues for human review workflows.
289

290
```java { .api }
291
// Create comment
292
CreateCommentResponse create(CreateCommentRequest request);
293

294
// Get comments
295
GetCommentsResponse get();
296

297
// Manage annotation queues
298
PaginatedAnnotationQueues listQueues();
299
AnnotationQueue getQueue(String queueId);
300
```
301

302
[Comments and Annotations](./comments-annotations.md)
303

304
### Project and Organization Management
305

306
Manage projects, API keys, and organization memberships (requires organization-scoped API key for most operations).
307

308
```java { .api }
309
// Get projects
310
Projects get();
311

312
// Create project (requires org-scoped key)
313
Project create(CreateProjectRequest request);
314

315
// Manage API keys (requires org-scoped key)
316
ApiKeyList getApiKeys(String projectId);
317
ApiKeyResponse createApiKey(String projectId, CreateApiKeyRequest request);
318
```
319

320
[Projects and Organizations](./projects-organizations.md)
321

322
### SCIM User Provisioning
323

324
SCIM 2.0 user provisioning for organization user management (requires organization-scoped API key).
325

326
```java { .api }
327
// List users
328
ScimUsersListResponse listUsers();
329
ScimUsersListResponse listUsers(ListUsersRequest request);
330

331
// Create user
332
ScimUser createUser(CreateUserRequest request);
333

334
// Get user
335
ScimUser getUser(String userId);
336
```
337

338
[SCIM](./scim.md)
339

340
### Media Management
341

342
Get media records and presigned upload URLs for media files.
343

344
```java { .api }
345
// Get media record
346
GetMediaResponse get(String mediaId);
347

348
// Get presigned upload URL
349
GetMediaUploadUrlResponse getUploadUrl(GetMediaUploadUrlRequest request);
350
```
351

352
[Media](./media.md)
353

354
### Health Checks
355

356
Check API and database health.
357

358
```java { .api }
359
HealthResponse health();
360
```
361

362
[Health](./health.md)
363

364
## Additional Resources
365

366
- [Exception Handling](./exceptions.md) - All exception types and error handling patterns
367
- [Common Types](./common-types.md) - Shared domain objects and type definitions
368
- [Pagination](./pagination.md) - Pagination utilities and metadata
369

370
## Notes
371

372
- This client is auto-generated from the Langfuse API specification using Fern
373
- The recommended approach for tracing is via OpenTelemetry instrumentation rather than direct Ingestion API usage
374
- Most methods provide 3 overloads: no parameters, with request object, with request and RequestOptions
375
- All list endpoints support pagination with consistent MetaResponse format
376
- Organization-level operations require organization-scoped API keys
377