# Source: https://langfuse.com/docs/metrics/features/metrics-api.md

---
title: Metrics API
sidebarTitle: Metrics API
description: Retrieve custom metrics from Langfuse for flexible analytics and reporting.
---

# Metrics API

```
GET /api/public/metrics
```

The **Metrics API** enables you to retrieve customized analytics from your Langfuse data.
This endpoint allows you to specify dimensions, metrics, filters, and time granularity to build powerful custom reports and dashboards for your LLM applications.

## Metrics API v2 (Beta) [#v2]

<Callout type="warning">

The v2 Metrics API is currently in **beta**. The API is stable for production use, but some parameters and behaviors may change based on user feedback before general availability.

**Cloud-only (Beta):** The v2 Metrics API is only available on Langfuse Cloud and currently in beta. We are working on a robust migration path for self-hosted deployments.

**Data availability note:** When using current SDK versions, data may take approximately 5 minutes to appear on v2 endpoints. We will be releasing updated SDK versions soon that will make data available immediately.

</Callout>

```
GET /api/public/v2/metrics
```

The v2 Metrics API provides significant performance improvements through an optimized data architecture built on a new events table schema that minimizes database work per query.

### Key Changes from v1

**The `traces` view is no longer available in v2.** Instead, use the `observations` view which is both faster and more powerful compared to v1.

### Available Views in v2

| View                 | Description                                                         |
| -------------------- | ------------------------------------------------------------------- |
| `observations`       | Query observation-level data with optional trace-level aggregations |
| `scores-numeric`     | Query numeric and boolean scores                                    |
| `scores-categorical` | Query categorical (string) scores                                   |

### Row Limit

The v2 Metrics API enforces a default `rowLimit` of 100 rows per query to ensure consistent performance. You can specify a custom `rowLimit` in your query to override this default.

### High Cardinality Dimensions

Certain dimensions like `id`, `traceId`, `userId`, and `sessionId` cannot be used for grouping in the v2 Metrics API. Grouping by these high cardinality fields is extremely expensive and rarely useful in practice. These dimensions remain available for filtering.

### Example: Most expensive models used in observations

```bash
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  -G \
  --data-urlencode 'query={
    "view": "observations",
    "metrics": [{"measure": "totalCost", "aggregation": "sum"}],
    "dimensions": [{"field": "providedModelName"}],
    "filters": [],
    "fromTimestamp": "2025-12-01T00:00:00Z",
    "toTimestamp": "2025-12-16T00:00:00Z",
    "orderBy": [{"field": "totalCost_sum", "direction": "desc"}]
  }' \
  https://cloud.langfuse.com/api/public/v2/metrics
```

<Callout type="info">

**API Reference:** See the full [v2 Metrics API Reference](https://api.reference.langfuse.com/#tag/metricsv2/GET/api/public/v2/metrics) for all available parameters, response schemas, and interactive examples.

</Callout>

## Metrics API v1 [#v1]

The Metrics API supports querying across different views (traces, observations, scores) and allows you to:

- Select specific dimensions to group your data
- Apply multiple metrics with different aggregation methods
- Filter data based on metadata, timestamps, and other properties
- Analyze data across time with customizable granularity
- Order results according to your needs

## Query Parameters

The API accepts a JSON query object passed as a URL-encoded parameter:

| Parameter | Type        | Description                                                |
| --------- | ----------- | ---------------------------------------------------------- |
| `query`   | JSON string | The encoded query object defining what metrics to retrieve |

### Query Object Structure

| Field           | Type   | Required | Description                                                                                                                                                              |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `view`          | string | Yes      | The data view to query: `"traces"`, `"observations"`, `"scores-numeric"`, or `"scores-categorical"`                                                                      |
| `dimensions`    | array  | No       | Array of dimension objects to group by, e.g. `[{ "field": "name" }]`                                                                                                     |
| `metrics`       | array  | Yes      | Array of metric objects to calculate, e.g. `[{ "measure": "latency", "aggregation": "p95" }]`                                                                            |
| `filters`       | array  | No       | Array of filter objects to narrow results, e.g. `[{ "column": "metadata", "operator": "contains", "key": "customKey", "value": "customValue", "type": "stringObject" }]` |
| `timeDimension` | object | No       | Configuration for time-based analysis, e.g. `{ "granularity": "day" }`                                                                                                   |
| `fromTimestamp` | string | Yes      | ISO timestamp for the start of the query period                                                                                                                          |
| `toTimestamp`   | string | Yes      | ISO timestamp for the end of the query period                                                                                                                            |
| `orderBy`       | array  | No       | Specification for result ordering, e.g. `[{ "field": "name", "direction": "asc" }]`                                                                                      |

### Dimension Object Structure

```json
{ "field": "name" }
```

### Metric Object Structure

```json
{ "measure": "count", "aggregation": "count" }
```

Common measure types include:

- `count` - Count of records
- `latency` - Duration/latency metrics

Aggregation types include:

- `sum` - Sum of values
- `avg` - Average of values
- `count` - Count of records
- `max` - Maximum value
- `min` - Minimum value
- `p50` - 50th percentile
- `p75` - 75th percentile
- `p90` - 90th percentile
- `p95` - 95th percentile
- `p99` - 99th percentile

### Filter Object Structure

```json
{
  "column": "metadata",
  "operator": "contains",
  "key": "customKey",
  "value": "customValue",
  "type": "stringObject"
}
```

### Time Dimension Object

```json
{
  "granularity": "day"
}
```

Supported granularities include: `hour`, `day`, `week`, `month`, and `auto`.

## Example

Here's an example of querying the number of traces grouped by name:

<LangTabs items={["API", "Python SDK"]}>
  <Tab label="API">

```bash
curl \
-H "Authorization: Basic <BASIC AUTH HEADER>" \
-G \
--data-urlencode 'query={
  "view": "traces",
  "metrics": [{"measure": "count", "aggregation": "count"}],
  "dimensions": [{"field": "name"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}' \
https://cloud.langfuse.com/api/public/metrics
```

  </Tab>
  <Tab label="Python SDK">

```python
query = """
{
  "view": "traces",
  "metrics": [{"measure": "count", "aggregation": "count"}],
  "dimensions": [{"field": "name"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}
"""

langfuse.api.metrics.metrics(query = query)
```

  </Tab>
</LangTabs>

Response:

```json
{
  "data": [
    { "name": "trace-test-2", "count_count": "10" },
    { "name": "trace-test-3", "count_count": "5" },
    { "name": "trace-test-1", "count_count": "3" }
  ]
}
```

## Data Model

The Metrics API provides access to several data views, each with its own set of dimensions and metrics you can query. This section outlines the available options for each view.

### Available Views

| View                 | Description                         |
| -------------------- | ----------------------------------- |
| `traces`             | Query data at the trace level       |
| `observations`       | Query data at the observation level |
| `scores-numeric`     | Query numeric and boolean scores    |
| `scores-categorical` | Query categorical (string) scores   |

### Trace Dimensions

| Dimension         | Type     | Description                             |
| ----------------- | -------- | --------------------------------------- |
| `id`              | string   | Trace ID                                |
| `name`            | string   | Trace name                              |
| `tags`            | string[] | Trace tags                              |
| `userId`          | string   | User ID associated with the trace       |
| `sessionId`       | string   | Session ID associated with the trace    |
| `release`         | string   | Release tag                             |
| `version`         | string   | Version tag                             |
| `environment`     | string   | Environment (e.g., production, staging) |
| `observationName` | string   | Name of related observations            |
| `scoreName`       | string   | Name of related scores                  |

### Trace Metrics

| Metric              | Description                         |
| ------------------- | ----------------------------------- |
| `count`             | Count of traces                     |
| `observationsCount` | Count of observations within traces |
| `scoresCount`       | Count of scores within traces       |
| `latency`           | Trace duration in milliseconds      |
| `totalTokens`       | Total tokens used in the trace      |
| `totalCost`         | Total cost of the trace             |

### Observation Dimensions

| Dimension             | Type   | Description                             |
| --------------------- | ------ | --------------------------------------- |
| `id`                  | string | Observation ID                          |
| `traceId`             | string | Associated trace ID                     |
| `traceName`           | string | Name of the parent trace                |
| `environment`         | string | Environment (e.g., production, staging) |
| `parentObservationId` | string | ID of parent observation                |
| `type`                | string | Observation type                        |
| `name`                | string | Observation name                        |
| `level`               | string | Log level                               |
| `version`             | string | Version                                 |
| `providedModelName`   | string | Model name                              |
| `promptName`          | string | Prompt name                             |
| `promptVersion`       | string | Prompt version                          |
| `userId`              | string | User ID from parent trace               |
| `sessionId`           | string | Session ID from parent trace            |
| `traceRelease`        | string | Release from parent trace               |
| `traceVersion`        | string | Version from parent trace               |
| `scoreName`           | string | Related score name                      |

### Observation Metrics

| Metric             | Description                          |
| ------------------ | ------------------------------------ |
| `count`            | Count of observations                |
| `latency`          | Observation duration in milliseconds |
| `totalTokens`      | Total tokens used                    |
| `totalCost`        | Total cost                           |
| `timeToFirstToken` | Time to first token in milliseconds  |
| `countScores`      | Count of related scores              |

### Score Dimensions (Common)

| Dimension                  | Type   | Description                                |
| -------------------------- | ------ | ------------------------------------------ |
| `id`                       | string | Score ID                                   |
| `name`                     | string | Score name                                 |
| `environment`              | string | Environment                                |
| `source`                   | string | Score source                               |
| `dataType`                 | string | Data type                                  |
| `traceId`                  | string | Related trace ID                           |
| `traceName`                | string | Related trace name                         |
| `userId`                   | string | User ID from trace                         |
| `sessionId`                | string | Session ID from trace                      |
| `observationId`            | string | Related observation ID                     |
| `observationName`          | string | Related observation name                   |
| `observationModelName`     | string | Model used in related observation          |
| `observationPromptName`    | string | Prompt name used in related observation    |
| `observationPromptVersion` | string | Prompt version used in related observation |
| `configId`                 | string | Configuration ID                           |

### Score Metrics

#### Numeric Scores

| Metric  | Description         |
| ------- | ------------------- |
| `count` | Count of scores     |
| `value` | Numeric score value |

#### Categorical Scores

| Metric  | Description     |
| ------- | --------------- |
| `count` | Count of scores |

Categorical scores have an additional dimension:

| Dimension     | Type   | Description                           |
| ------------- | ------ | ------------------------------------- |
| `stringValue` | string | String value of the categorical score |

## Daily Metrics API (Legacy) [#daily-metrics]

<Callout type="warning">

This API is a legacy API. For new use cases, please use the [Metrics API](/docs/analytics/metrics-api) instead.
It has higher rate-limits and offers more flexibility.

</Callout>

```
GET /api/public/metrics/daily
```

Via the **Daily Metrics API**, you can retrieve aggregated daily usage and cost metrics from Langfuse for downstream use, e.g., in analytics, billing, and rate-limiting. The API allows you to filter by application type, user, or tags for tailored data retrieval.

See [API reference](https://api.reference.langfuse.com/#tag/metrics/GET/api/public/metrics/daily) for more details.

### Overview

Returned data includes daily timeseries of:

- [Cost](/docs/model-usage-and-cost) in USD
- Trace and observation count
- Break down by model name
- Usage (e.g. tokens) broken down by input and output usage
- [Cost](/docs/model-usage-and-cost) in USD
- Trace and observation count

Optional filters:

- `traceName` to commonly filter by the application type, depending on how you use `name` in your traces
- `userId` to filter by [user](/docs/tracing-features/users)
- `tags` to filter by [tags](/docs/tracing-features/tags)
- `fromTimestamp`
- `toTimestamp`

Missing a key metric or filter? Request it via our [idea board](/ideas).

### Example

```
GET /api/public/metrics/daily?traceName=my-copilot&userId=john&limit=2
```

```json
{
  "data": [
    {
      "date": "2024-02-18",
      "countTraces": 1500,
      "countObservations": 3000,
      "totalCost": 102.19,
      "usage": [
        {
          "model": "llama2",
          "inputUsage": 1200,
          "outputUsage": 1300,
          "totalUsage": 2500,
          "countTraces": 1000,
          "countObservations": 2000,
          "totalCost": 50.19
        },
        {
          "model": "gpt-4",
          "inputUsage": 500,
          "outputUsage": 550,
          "totalUsage": 1050,
          "countTraces": 500,
          "countObservations": 1000,
          "totalCost": 52.0
        }
      ]
    },
    {
      "date": "2024-02-17",
      "countTraces": 1250,
      "countObservations": 2500,
      "totalCost": 250.0,
      "usage": [
        {
          "model": "llama2",
          "inputUsage": 1000,
          "outputUsage": 1100,
          "totalUsage": 2100,
          "countTraces": 1250,
          "countObservations": 2500,
          "totalCost": 250.0
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 2,
    "totalItems": 60,
    "totalPages": 30
  }
}
```