Query Data via SDKs

Langfuse is open-source and data tracked with Langfuse is open. Use the Python and JS/TS SDKs to query the same public APIs without writing raw HTTP requests.

Common use cases:

Query row-level observations for evaluation pipelines, few-shot examples, or fine-tuning datasets.
Query aggregate cost, usage, latency, volume, and score metrics for dashboards or billing workflows.
Programmatically create datasets.

If you are new to Langfuse, we recommend familiarizing yourself with the Langfuse data model.

Note

New data is typically available for querying within 15-30 seconds of ingestion, though processing times may vary at times. Please visit status.langfuse.com if you encounter any issues.

SDKs

Via the SDKs for Python and JS/TS you can easily query the API without having to write the HTTP requests yourself.

The api namespace is auto-generated from the Public API (OpenAPI). Method names mirror REST resources and support filters and pagination.

Warning

From Python SDK v4 and JS/TS SDK v5 onward, the high-performance observations and metrics APIs are the defaults:

api.observations (formerly api.observations_v_2 / api.observationsV2)
api.metrics (formerly api.metrics_v_2 / api.metricsV2)

Scores API v3 is available as api.scores_v3 in Python SDK 4.8.1+ and api.scoresV3 in JS/TS SDK 5.5.0+. The api.scores v2 reads are deprecated; see Migration of deprecated APIs. In Python SDK v5 and JS/TS SDK v6, Scores API v3 moves to api.scores.get_many / api.scores.getMany, and api.scores_v3 / api.scoresV3 are removed.

The old v2 aliases were removed in Python SDK v4 and JS/TS SDK v5.

The api.legacy.* resources call the deprecated endpoints. Langfuse Cloud serves these endpoints until November 16, 2026 (2026-11-16). See Migration of deprecated APIs for replacements and the endpoint reference.

Python SDK v5 and JS/TS SDK v6 require Langfuse v4 and have no api.legacy namespace. They remove all three legacy resources: api.legacy.observations_v1 / api.legacy.observationsV1 (use api.observations), api.legacy.metrics_v1 / api.legacy.metricsV1 (use api.metrics), and api.legacy.score_v1 / api.legacy.scoreV1, including its create and delete methods (use api.scores.create and api.scores.delete). They also remove the deprecated api.scores v2 reads. See the Python v4 → v5 and JS/TS v5 → v6 upgrade guides.

Python SDK

JS/TS SDK

pip install langfuse

from langfuse import get_client
langfuse = get_client()  # uses environment variables to authenticate

Observations

observations = langfuse.api.observations.get_many(
    trace_id="abcdef1234",
    type="GENERATION",
    limit=100,
    fields="core,basic,usage"
)

Use trace_id to retrieve the observations that belong to a single trace. Use parent_observation_id in the response to reconstruct an observation tree when needed.

Metrics

For the full query schema, supported dimensions, filters, and examples, see the Metrics API v2 documentation.

query = """
{
  "view": "observations",
  "metrics": [{"measure": "totalCost", "aggregation": "sum"}],
  "dimensions": [{"field": "providedModelName"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}
"""

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

Other resources

Sessions:

Sessions do not have a dedicated endpoint. Fetch the observations that share a sessionId and group them client-side (migration details).

import json

session_observations = langfuse.api.observations.get_many(
    filter=json.dumps([
        {"type": "string", "column": "sessionId", "operator": "=", "value": "chat-session-42"},
    ]),
    fields="core,basic,io",
    limit=50,
)

Scores:

# Scores API v3 (Python SDK v5+; recommended)
scores = langfuse.api.scores.get_many(id="ScoreId")

# Scores API v3 (Python SDK 4.8.1+ on v4)
scores = langfuse.api.scores_v3.get_many_v3(id="ScoreId")

# Scores API v2 (Python SDK v4 only; deprecated, sunset date: Nov 16, 2026)
scores = langfuse.api.scores.get_many(score_ids="ScoreId")

To move existing v2 score reads to v3, see Migration of deprecated APIs.

Prompts:

Please refer to the prompt management documentation on fetching prompts.

Datasets:

# Namespaces:
# - langfuse.api.datasets.*
# - langfuse.api.dataset_items.*
# - langfuse.api.experiments.* (Python SDK 4.13.1+)

Async equivalents

# All endpoints are also available as async under `async_api`:
observations = await langfuse.async_api.observations.get_many(
    trace_id="abcdef1234",
    limit=100,
    fields="core,basic,usage",
)
metrics = await langfuse.async_api.metrics.metrics(query = query)

For row-level observation filters, field selection, and cursor pagination, see the Observations API v2 documentation.

Note

The methods on the langfuse.api are auto-generated from the API reference and cover all entities. You can explore more entities via Intellisense

npm install @langfuse/client

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

Observations

const observations = await langfuse.api.observations.getMany({
  traceId: "abcdef1234",
  type: "GENERATION",
  limit: 100,
  fields: "core,basic,usage",
});

Use traceId to retrieve the observations that belong to a single trace. Use parentObservationId in the response to reconstruct an observation tree when needed.

For row-level observation filters, field selection, and cursor pagination, see the Observations API v2 documentation.

Metrics

For the full query schema, supported dimensions, filters, and examples, see the Metrics API v2 documentation.

const query = {
  view: "observations",
  metrics: [{ measure: "totalCost", aggregation: "sum" }],
  dimensions: [{ field: "providedModelName" }],
  filters: [],
  fromTimestamp: "2025-05-01T00:00:00Z",
  toTimestamp: "2025-05-13T00:00:00Z",
};

const metrics = await langfuse.api.metrics.metrics({
  query: JSON.stringify(query),
});

Other resources

Sessions:

Sessions do not have a dedicated endpoint. Fetch the observations that share a sessionId and group them client-side (migration details).

const sessionObservations = await langfuse.api.observations.getMany({
  filter: JSON.stringify([
    {
      type: "string",
      column: "sessionId",
      operator: "=",
      value: "chat-session-42",
    },
  ]),
  fields: "core,basic,io",
  limit: 50,
});

Scores:

// Scores API v3 (JS/TS SDK v6+; recommended)
const scoresV3 = await langfuse.api.scores.getMany();

// Scores API v3 (JS/TS SDK 5.5.0+ on v5)
const scoresV3Legacy = await langfuse.api.scoresV3.getManyV3();

// Scores API v2 (JS/TS SDK v5 only; deprecated, sunset date: Nov 16, 2026)
const scores = await langfuse.api.scores.getMany();

To move existing v2 score reads to v3, see Migration of deprecated APIs.

Prompts:

Please refer to the prompt management documentation on fetching prompts.

Datasets:

// Namespaces:
// - langfuse.api.datasets.*
// - langfuse.api.datasetItems.*
// - langfuse.api.experiments.* (JS/TS SDK 5.10.0+)

Explore more entities via Intellisense on langfuse.api.

Python SDKJS/TS SDK

pip install langfuse

from langfuse import get_client
langfuse = get_client()  # uses environment variables to authenticate

Observations

observations = langfuse.api.observations.get_many(
    trace_id="abcdef1234",
    type="GENERATION",
    limit=100,
    fields="core,basic,usage"
)

Use trace_id to retrieve the observations that belong to a single trace. Use parent_observation_id in the response to reconstruct an observation tree when needed.

Metrics

For the full query schema, supported dimensions, filters, and examples, see the Metrics API v2 documentation.

query = """
{
  "view": "observations",
  "metrics": [{"measure": "totalCost", "aggregation": "sum"}],
  "dimensions": [{"field": "providedModelName"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}
"""

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

Other resources

Sessions:

Sessions do not have a dedicated endpoint. Fetch the observations that share a sessionId and group them client-side (migration details).

import json

session_observations = langfuse.api.observations.get_many(
    filter=json.dumps([
        {"type": "string", "column": "sessionId", "operator": "=", "value": "chat-session-42"},
    ]),
    fields="core,basic,io",
    limit=50,
)

Scores:

# Scores API v3 (Python SDK v5+; recommended)
scores = langfuse.api.scores.get_many(id="ScoreId")

# Scores API v3 (Python SDK 4.8.1+ on v4)
scores = langfuse.api.scores_v3.get_many_v3(id="ScoreId")

# Scores API v2 (Python SDK v4 only; deprecated, sunset date: Nov 16, 2026)
scores = langfuse.api.scores.get_many(score_ids="ScoreId")

To move existing v2 score reads to v3, see Migration of deprecated APIs.

Prompts:

Please refer to the prompt management documentation on fetching prompts.

Datasets:

# Namespaces:
# - langfuse.api.datasets.*
# - langfuse.api.dataset_items.*
# - langfuse.api.experiments.* (Python SDK 4.13.1+)

Async equivalents

# All endpoints are also available as async under `async_api`:
observations = await langfuse.async_api.observations.get_many(
    trace_id="abcdef1234",
    limit=100,
    fields="core,basic,usage",
)
metrics = await langfuse.async_api.metrics.metrics(query = query)

For row-level observation filters, field selection, and cursor pagination, see the Observations API v2 documentation.

Note

The methods on the langfuse.api are auto-generated from the API reference and cover all entities. You can explore more entities via Intellisense

npm install @langfuse/client

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

Observations

const observations = await langfuse.api.observations.getMany({
  traceId: "abcdef1234",
  type: "GENERATION",
  limit: 100,
  fields: "core,basic,usage",
});

Use traceId to retrieve the observations that belong to a single trace. Use parentObservationId in the response to reconstruct an observation tree when needed.

For row-level observation filters, field selection, and cursor pagination, see the Observations API v2 documentation.

Metrics

For the full query schema, supported dimensions, filters, and examples, see the Metrics API v2 documentation.

const query = {
  view: "observations",
  metrics: [{ measure: "totalCost", aggregation: "sum" }],
  dimensions: [{ field: "providedModelName" }],
  filters: [],
  fromTimestamp: "2025-05-01T00:00:00Z",
  toTimestamp: "2025-05-13T00:00:00Z",
};

const metrics = await langfuse.api.metrics.metrics({
  query: JSON.stringify(query),
});

Other resources

Sessions:

Sessions do not have a dedicated endpoint. Fetch the observations that share a sessionId and group them client-side (migration details).

const sessionObservations = await langfuse.api.observations.getMany({
  filter: JSON.stringify([
    {
      type: "string",
      column: "sessionId",
      operator: "=",
      value: "chat-session-42",
    },
  ]),
  fields: "core,basic,io",
  limit: 50,
});

Scores:

// Scores API v3 (JS/TS SDK v6+; recommended)
const scoresV3 = await langfuse.api.scores.getMany();

// Scores API v3 (JS/TS SDK 5.5.0+ on v5)
const scoresV3Legacy = await langfuse.api.scoresV3.getManyV3();

// Scores API v2 (JS/TS SDK v5 only; deprecated, sunset date: Nov 16, 2026)
const scores = await langfuse.api.scores.getMany();

To move existing v2 score reads to v3, see Migration of deprecated APIs.

Prompts:

Please refer to the prompt management documentation on fetching prompts.

Datasets:

// Namespaces:
// - langfuse.api.datasets.*
// - langfuse.api.datasetItems.*
// - langfuse.api.experiments.* (JS/TS SDK 5.10.0+)

Explore more entities via Intellisense on langfuse.api.

To move existing trace or observation reads to v2, see Observations API v2.
To move existing score reads to v3, see Migration of deprecated APIs.
To move existing metrics queries to v2, see Metrics API v2.
For large-scale data exports (e.g., all traces for fine-tuning or analytics), consider using the Blob Storage Export to automatically sync data to S3, GCS, or Azure on a schedule instead of paginating through the API.
To manually export filtered data from the Langfuse UI, see Export from UI.

query = """ { "view": "observations", "metrics": [{"measure": "totalCost", "aggregation": "sum"}], "dimensions": [{"field": "providedModelName"}], "filters": [], "fromTimestamp": "2025-05-01T00:00:00Z", "toTimestamp": "2025-05-13T00:00:00Z" } """ metrics = langfuse.api.metrics.metrics(query = query)

import json session_observations = langfuse.api.observations.get_many( filter=json.dumps([ {"type": "string", "column": "sessionId", "operator": "=", "value": "chat-session-42"}, ]), fields="core,basic,io", limit=50, )

# Scores API v3 (Python SDK v5+; recommended) scores = langfuse.api.scores.get_many(id="ScoreId") # Scores API v3 (Python SDK 4.8.1+ on v4) scores = langfuse.api.scores_v3.get_many_v3(id="ScoreId") # Scores API v2 (Python SDK v4 only; deprecated, sunset date: Nov 16, 2026) scores = langfuse.api.scores.get_many(score_ids="ScoreId")

# All endpoints are also available as async under `async_api`: observations = await langfuse.async_api.observations.get_many( trace_id="abcdef1234", limit=100, fields="core,basic,usage", ) metrics = await langfuse.async_api.metrics.metrics(query = query)

const query = { view: "observations", metrics: [{ measure: "totalCost", aggregation: "sum" }], dimensions: [{ field: "providedModelName" }], filters: [], fromTimestamp: "2025-05-01T00:00:00Z", toTimestamp: "2025-05-13T00:00:00Z", }; const metrics = await langfuse.api.metrics.metrics({ query: JSON.stringify(query), });

const sessionObservations = await langfuse.api.observations.getMany({ filter: JSON.stringify([ { type: "string", column: "sessionId", operator: "=", value: "chat-session-42", }, ]), fields: "core,basic,io", limit: 50, });

// Scores API v3 (JS/TS SDK v6+; recommended) const scoresV3 = await langfuse.api.scores.getMany(); // Scores API v3 (JS/TS SDK 5.5.0+ on v5) const scoresV3Legacy = await langfuse.api.scoresV3.getManyV3(); // Scores API v2 (JS/TS SDK v5 only; deprecated, sunset date: Nov 16, 2026) const scores = await langfuse.api.scores.getMany();

Query via SDKs

Query Data via SDKs

SDKs

Observations

Metrics

Other resources

Async equivalents

Observations

Metrics

Other resources

Observations

Metrics

Other resources

Async equivalents

Observations

Metrics

Other resources

Related Resources

Observations

Metrics

Other resources

Async equivalents

Observations

Metrics

Other resources