0
# Metrics
1

2
The Metrics API provides access to project-level metrics and analytics using a JSON query object.
3

4
## Capabilities
5

6
### MetricsClient
7

8
Client for retrieving project metrics.
9

10
```java { .api }
11
/**
12
 * Get metrics from the Langfuse project using a query object
13
 *
14
 * @param request Metrics query with JSON string
15
 * @param requestOptions Optional request configuration
16
 */
17
MetricsResponse metrics(GetMetricsRequest request);
18
MetricsResponse metrics(GetMetricsRequest request, RequestOptions requestOptions);
19
```
20

21
**Usage Example:**
22

23
```java
24
import com.langfuse.client.LangfuseClient;
25
import com.langfuse.client.resources.metrics.requests.*;
26
import com.langfuse.client.resources.metrics.types.*;
27

28
LangfuseClient client = LangfuseClient.builder()
29
    .url("https://cloud.langfuse.com")
30
    .credentials("pk-lf-...", "sk-lf-...")
31
    .build();
32

33
// Create metrics query (JSON string)
34
String query = """
35
    {
36
        "metric": "traces",
37
        "filters": {
38
            "environment": "production",
39
            "fromTimestamp": "2025-10-01T00:00:00Z",
40
            "toTimestamp": "2025-10-14T23:59:59Z"
41
        },
42
        "groupBy": ["userId", "name"]
43
    }
44
    """;
45

46
GetMetricsRequest request = GetMetricsRequest.builder()
47
    .query(query)
48
    .build();
49

50
MetricsResponse response = client.metrics().metrics(request);
51

52
// Response data is a list of result maps
53
List<Map<String, Object>> data = response.getData();
54
System.out.println("Metrics data: " + data);
55
```
56

57
## Request Types
58

59
### GetMetricsRequest
60

61
```java { .api }
62
/**
63
 * Request for querying metrics
64
 */
65
public final class GetMetricsRequest {
66
    String getQuery();  // JSON query string
67

68
    static Builder builder();
69
}
70
```
71

72
## Response Types
73

74
### MetricsResponse
75

76
```java { .api }
77
/**
78
 * Metrics query response
79
 */
80
public final class MetricsResponse {
81
    List<Map<String, Object>> getData();  // List of result maps with metric values and dimensions
82

83
    static Builder builder();
84
}
85
```
86

87
## Query Structure
88

89
The query parameter accepts a JSON string with the following structure:
90

91
```json
92
{
93
  "metric": "traces|observations|scores|costs",
94
  "filters": {
95
    "environment": "string",
96
    "userId": "string",
97
    "name": "string",
98
    "fromTimestamp": "ISO 8601 timestamp",
99
    "toTimestamp": "ISO 8601 timestamp",
100
    "tags": ["tag1", "tag2"]
101
  },
102
  "groupBy": ["userId", "name", "environment"],
103
  "aggregation": "count|sum|avg|min|max"
104
}
105
```
106

107
## Example Queries
108

109
### Trace Count by User
110

111
```java
112
String query = """
113
    {
114
        "metric": "traces",
115
        "filters": {
116
            "fromTimestamp": "2025-10-01T00:00:00Z",
117
            "toTimestamp": "2025-10-31T23:59:59Z"
118
        },
119
        "groupBy": ["userId"],
120
        "aggregation": "count"
121
    }
122
    """;
123

124
GetMetricsRequest request = GetMetricsRequest.builder()
125
    .query(query)
126
    .build();
127

128
MetricsResponse response = client.metrics().metrics(request);
129
```
130

131
### Total Cost by Environment
132

133
```java
134
String query = """
135
    {
136
        "metric": "costs",
137
        "filters": {
138
            "fromTimestamp": "2025-10-01T00:00:00Z"
139
        },
140
        "groupBy": ["environment"],
141
        "aggregation": "sum"
142
    }
143
    """;
144

145
GetMetricsRequest request = GetMetricsRequest.builder()
146
    .query(query)
147
    .build();
148

149
MetricsResponse response = client.metrics().metrics(request);
150
```
151

152
### Average Score by Name
153

154
```java
155
String query = """
156
    {
157
        "metric": "scores",
158
        "filters": {
159
            "name": "quality",
160
            "fromTimestamp": "2025-10-01T00:00:00Z"
161
        },
162
        "groupBy": ["environment"],
163
        "aggregation": "avg"
164
    }
165
    """;
166

167
GetMetricsRequest request = GetMetricsRequest.builder()
168
    .query(query)
169
    .build();
170

171
MetricsResponse response = client.metrics().metrics(request);
172
```
173

174
## Best Practices
175

176
1. **Use Date Filters**: Always include fromTimestamp/toTimestamp for performance
177
2. **Limit Grouping**: Avoid grouping by too many dimensions
178
3. **Cache Results**: Cache metrics responses for dashboards
179
4. **Handle Response**: Parse the Object response based on your query structure
180
5. **Monitor Performance**: Track query performance for large datasets
181

182
## Related Documentation
183

184
- [Traces and Observations](./traces-observations.md) - Trace data sources
185
- [Scores](./scores.md) - Score data sources
186