langfuse_client/metrics

GET /api/public/v2/metrics — server-side aggregations over Langfuse score data. Build a query with score_count_query / score_value_query and pass it to the matching list_* function.

The Langfuse v2 metrics endpoint is BETA. This module exposes score count + avg-value queries grouped by (name, dataType, source), with optional server-side filters. Broader surface (other measures, views, dimensions) will follow the same shape once the endpoint stabilises.

Types

Filter

</>

A server-side filter on a v2 metrics query. The Langfuse API uses a tagged union — the type field discriminates the shape; this module mirrors that with one Gleam variant per supported filter type.

pub type Filter {
  StringOptions(
    column: String,
    operator: StringOptionsOperator,
    values: List(String),
  )
}

Constructors

```
StringOptions(
  column: String,
  operator: StringOptionsOperator,
  values: List(String),
)
```
any of / none of matching against a column’s string values. E.g., restricting name (scorer) to a specific set.

ScoreCountQuery

</>

Filters for list_score_counts. Window is [from_timestamp, to_timestamp) in ISO 8601. Build with score_count_query.

pub type ScoreCountQuery {
  ScoreCountQuery(
    view: ScoreView,
    from_timestamp: String,
    to_timestamp: String,
    filters: List(Filter),
  )
}

Constructors

ScoreCountQuery(
  view: ScoreView,
  from_timestamp: String,
  to_timestamp: String,
  filters: List(Filter),
)

ScoreCountRow

</>

One row of the data array: the count of scores grouped by the (name, data_type, source) triple. count is the sum_count measure decoded from its string representation.

pub type ScoreCountRow {
  ScoreCountRow(
    name: String,
    data_type: String,
    source: String,
    count: Int,
  )
}

Constructors

ScoreCountRow(
  name: String,
  data_type: String,
  source: String,
  count: Int,
)

ScoreValueQuery

</>

Filters for list_score_values. The view is implicitly numeric — the API rejects value measure on categorical scores. Build with score_value_query.

pub type ScoreValueQuery {
  ScoreValueQuery(
    from_timestamp: String,
    to_timestamp: String,
    filters: List(Filter),
  )
}

Constructors

ScoreValueQuery(
  from_timestamp: String,
  to_timestamp: String,
  filters: List(Filter),
)

ScoreValueRow

</>

One row from a score-value query: the avg value of scores grouped by (name, data_type, source). The Langfuse API restricts the value measure to numeric/boolean scores; categorical scores are not included.

pub type ScoreValueRow {
  ScoreValueRow(
    name: String,
    data_type: String,
    source: String,
    avg_value: Float,
  )
}

Constructors

ScoreValueRow(
  name: String,
  data_type: String,
  source: String,
  avg_value: Float,
)

ScoreView

</>

Which family of scores to aggregate over.

ScoresNumeric covers NUMERIC and BOOLEAN scores.
ScoresCategorical covers CATEGORICAL scores.

pub type ScoreView {
  ScoresNumeric
  ScoresCategorical
}

Constructors

```
ScoresNumeric
```
```
ScoresCategorical
```

StringOptionsOperator

</>

Set-membership operator for StringOptions filters.

pub type StringOptionsOperator {
  AnyOf
  NoneOf
}

Constructors

```
AnyOf
```
```
NoneOf
```

Values

decode

</>

pub fn decode(
  body: String,
) -> Result(List(ScoreCountRow), json.DecodeError)

Parse a GET /api/public/v2/metrics response body for a score-count query. Useful if you already have the raw body in hand (e.g. from a cached/recorded response).

decode_score_values

</>

pub fn decode_score_values(
  body: String,
) -> Result(List(ScoreValueRow), json.DecodeError)

Parse a GET /api/public/v2/metrics response body for a score-value query.

list_score_counts

</>

pub fn list_score_counts(
  c: client.Client,
  q: ScoreCountQuery,
) -> Result(List(ScoreCountRow), client.Error)

Aggregate score counts for the query. Returns one row per distinct (name, data_type, source) combination present in the window after filters are applied. Erlang-only — see langfuse_client/client module docs.

list_score_values

</>

pub fn list_score_values(
  c: client.Client,
  q: ScoreValueQuery,
) -> Result(List(ScoreValueRow), client.Error)

Aggregate avg score values for the query. One row per (name, data_type, source) combination over the window after filters are applied. Erlang-only — see langfuse_client/client module docs.

score_count_query

</>

pub fn score_count_query(
  view view: ScoreView,
  from from_timestamp: String,
  to to_timestamp: String,
  filters filters: List(Filter),
) -> ScoreCountQuery

Build a query for counts of scores grouped by (name, data_type, source) in the given window, with optional server-side filters.

score_value_query

</>

pub fn score_value_query(
  from from_timestamp: String,
  to to_timestamp: String,
  filters filters: List(Filter),
) -> ScoreValueQuery

Build a query for avg score values grouped by (name, data_type, source) in the given window, with optional server-side filters. Only numeric and boolean scores are returned.

scorer_names

</>

pub fn scorer_names(names: List(String)) -> Filter

Convenience: filter to scores whose name (scorer) is in the given list. Saves bytes on the wire and downstream work — server-side filter always preferred over client-side.