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.

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.

pip install langfuse

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

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

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

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

The older trace, observation, and metrics read APIs remain available, but they are not recommended as the default for new data extraction workflows because they are less performant at scale. See Upgrade to v2 data APIs for migration examples.

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

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.get(query = query)

Other resources

Sessions:

sessions = langfuse.api.sessions.list(limit=50)

Scores:

scores = langfuse.api.scores.get_many(score_ids = "ScoreId")

Prompts:

Please refer to the prompt management documentation on fetching prompts.

Datasets:

# Namespaces:
# - langfuse.api.datasets.*
# - langfuse.api.dataset_items.*
# - langfuse.api.dataset_run_items.*

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.get(query = query)

Common filtering & pagination

limit, cursor (pagination)
time range filters (e.g., from_start_time, to_start_time)
entity filters: user_id, session_id, trace_id, type, name, level, environment, version, etc.

See the Public API for the exact parameters per resource.

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();

// Retrieve row-level observations via Observations API v2
const observations = await langfuse.api.observations.getMany({
  traceId: "abcdef1234",
  type: "GENERATION",
  limit: 100,
  fields: "core,basic,usage",
});

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

// Fetch sessions and scores
const sessions = await langfuse.api.sessions.list();
const scores = await langfuse.api.scores.getMany();

// Explore more entities via Intellisense

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

To move existing trace, observation, or metrics read calls to v2, see Upgrade to v2 data APIs.
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.

Was this page helpful?

On this page