SDK로 데이터 조회하기(Query Data via SDKs)

Langfuse는 오픈소스이며 Langfuse로 추적한 데이터는 열려 있습니다. 이 문서는 raw HTTP 요청을 직접 작성하지 않고 Python과 JS/TS SDK로 같은 public API를 조회하는 방법을 설명해요. 행 단위 observations 조회, 집계 메트릭 조회, 데이터셋 생성 등 다양한 사용 사례를 다룹니다.

출처: 문서

본문

Langfuse는 오픈소스이며 Langfuse로 추적한 데이터는 열려 있습니다. raw HTTP 요청을 직접 작성하지 않고 Python과 JS/TS SDK를 사용해 같은 public API를 조회하세요.

일반적인 사용 사례:

평가 파이프라인, few-shot 예시, 파인튜닝 데이터셋을 위한 행 단위 observations 조회
대시보드나 청구 워크플로우를 위한 집계 비용, 사용량, 지연시간, 볼륨, 점수 메트릭 조회
프로그래매틱하게 데이터셋 생성

Langfuse가 처음이라면 Langfuse 데이터 모델 을 먼저 익히는 것을 권장합니다.

새 데이터는 보통 수집 후 15~30초 안에 조회 가능해집니다. 단, 처리 시간이 때때로 달라질 수 있습니다. 문제가 있으면 status.langfuse.com 을 방문해 주세요.

SDKs

Python과 JS/TS용 SDKs 를 통해 HTTP 요청을 직접 작성하지 않고도 API를 쉽게 조회할 수 있습니다.

api 네임스페이스는 Public API(OpenAPI)에서 자동 생성됩니다. 메서드 이름은 REST 리소스를 반영하며 필터와 페이지네이션을 지원합니다.

Python SDK v4와 JS/TS SDK v5부터 고성능 observations 및 metrics API가 기본값입니다:

api.observations (이전 api.observations_v_2 / api.observationsV2)
api.metrics (이전 api.metrics_v_2 / api.metricsV2)

Scores API v3는 Python SDK 4.8.1+의 api.scores_v3, JS/TS SDK 5.5.0+의 api.scoresV3로 사용할 수 있습니다. api.scores v2 읽기는 deprecated이며, Migration of deprecated APIs 를 참고하세요. 이전 v2 별칭은 Python SDK v4와 JS/TS SDK v5에서 제거되었습니다. api.legacy.* 리소스는 deprecated 엔드포인트를 호출합니다. Langfuse Cloud는 2026년 11월 16일(2026-11-16)까지 이 엔드포인트를 제공합니다. 대체 방법과 엔드포인트 참조는 Migration of deprecated APIs 를 참고하세요.

Python

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"
)

trace_id를 사용해 단일 trace에 속한 observations를 조회하세요. 필요 시 응답의 parent_observation_id를 사용해 observation 트리를 재구성할 수 있습니다.

Metrics:

전체 쿼리 스키마, 지원 차원, 필터, 예시는 Metrics API v2 문서 를 참고하세요.

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)

기타 리소스:

Sessions: Sessions에는 전용 엔드포인트가 없습니다. 같은 sessionId를 공유하는 observations를 조회해 클라이언트 쪽에서 그룹화하세요 (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 4.8.1+; recommended)
scores = langfuse.api.scores_v3.get_many_v3(id="ScoreId")

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

기존 v2 점수 읽기를 v3로 옮기려면 Migration of deprecated APIs 를 참고하세요.

Prompts: 프롬프트 조회는 prompt management 문서 를 참고하세요.

Datasets:

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

비동기 동등물:

# 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)

행 단위 observation 필터, 필드 선택, cursor 페이지네이션에 대해서는 Observations API v2 문서 를 참고하세요. langfuse.api의 메서드는 API 참조에서 자동 생성되며 모든 엔터티를 포함합니다. Intellisense로 더 많은 엔터티를 탐색할 수 있습니다.

JS/TS

npm install @langfuse/client

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

const langfuse = new LangfuseClient();