Public API

Public API

Langfuse는 개방적이며 커스텀 워크플로우와 통합으로 확장되도록 설계되었습니다. 이 문서는 프로젝트 수준 API의 사용 방법(자격 증명, 리전 base URL, SDK 접근, 데이터 수집/조회)을 설명해요. 모든 Langfuse 데이터와 기능이 API를 통해 제공됩니다.

출처: 문서

본문

Langfuse는 개방적이며 커스텀 워크플로우와 통합으로 확장되도록 설계되었습니다. 모든 Langfuse 데이터와 기능은 API를 통해 사용할 수 있습니다.

API에는 3가지 그룹이 있습니다:

  • 이 페이지 → 프로젝트 수준 API: 프로젝트 내 traces/evals/prompts/configuration CRUD
  • 조직 수준 API : 프로젝트, 사용자(SCIM), 권한 프로비저닝
  • Instance Management API : 셀프 호스팅 설치에서 조직 관리

API 참조(API reference)

이 페이지는 개념과 워크플로우를 다룹니다. 모든 엔드포인트의 완전한 요청/응답 계약(매개변수, 스키마, 인터랙티브 예시)은 API 참조를 참고하세요:

퀵스타트(Quickstart)

자격 증명 얻기

공개 키와 비밀 키는 Langfuse 프로젝트 설정에서 확인할 수 있습니다.

리전별 base URL 선택

/api/public

https://us.cloud.langfuse.com/api/public

https://cloud.langfuse.com/api/public

https://jp.cloud.langfuse.com/api/public

https://hipaa.cloud.langfuse.com/api/public

인증된 요청 보내기

예시:

curl -u public-key:secret-key https://cloud.langfuse.com/api/public/projects

결과 이해하기

성공적인 응답은 내 API 키와 연결된 프로젝트를 반환합니다:

{
  "data": [
    {
      "id": "clxxxx",
      "name": "My Project",
      "organization": {
        "id": "clyyyy",
        "name": "My Org"
      }
    }
  ]
}

나머지 Public API에도 같은 자격 증명과 리전 base URL을 사용하세요.

SDK로 접근

Langfuse Python SDK 와 JS/TS SDK 모두 공개 REST API에 대한 강타입 래퍼를 제공합니다. API 메서드는 두 SDK 모두에서 Langfuse 클라이언트 인스턴스의 api 프로퍼티로 접근할 수 있습니다.

에디터의 Intellisense로 API 메서드와 매개변수를 탐색할 수 있습니다. 더 많은 예시는 Query via SDKs 를 참고하세요.

Python SDK v4와 JS/TS SDK v5에서 고성능 observations와 metrics 리소스가 기본값입니다: api.observations와 api.metrics. Scores API v3는 Python SDK 4.8.1+의 api.scores_v3, JS/TS SDK 5.5.0+의 api.scoresV3로 사용할 수 있습니다. api.scores v2 읽기는 deprecated입니다(migration guide). Deprecated v1 리소스는 api.legacy.*(Python: *_v1, JS/TS: *V1) 아래로 이동했습니다. Observations API v2와 Metrics API v2는 Langfuse Cloud와 셀프 호스팅 Langfuse v4에서 사용할 수 있습니다. 셀프 호스팅 Langfuse v3에서는 api.legacy.* 리소스를 사용하세요. Versions & Compatibility 를 참고하세요.

prompts 를 가져올 때는 클라이언트 측 캐싱, 자동 재시도, 폴백을 활용하기 위해 Langfuse 클라이언트의 get_prompt(Python) / getPrompt(JS/TS) 메서드를 사용하세요.

Python SDK 사용 시:

from langfuse import get_client

langfuse = get_client()

# Retrieve row-level observations via Observations API v2
observations = langfuse.api.observations.get_many(
    trace_id="trace-id",
    fields="core,basic,usage",
    limit=100,
)

# Retrieve aggregates via Metrics API v2
metrics = langfuse.api.metrics.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"
}
""")

# explore more endpoints via Intellisense
langfuse.api.*
await langfuse.async_api.*

JS/TS SDK 사용 시:

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: "trace-id",
  fields: "core,basic,usage",
  limit: 100,
});

// Retrieve aggregates via Metrics API v2
const metrics = await langfuse.api.metrics.metrics({
  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"
  })
});

// explore more endpoints via Intellisense
langfuse.api.*

Java SDK: pom.xml에 다음을 추가해 설치합니다:

<dependencies>
  <dependency>
    <groupId>com.langfuse</groupId>
    <artifactId>langfuse-java</artifactId>
    <version>0.0.1-SNAPSHOT</version>
  </dependency>
</dependencies>

<repositories>
  <repository>
    <id>github</id>
    <name>GitHub Package Registry</name>
    <url>https://maven.pkg.github.com/langfuse/langfuse-java</url>
  </repository>
</repositories>

Java SDK를 인스턴스화하고 사용합니다:

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.prompts.types.PromptMetaListResponse;
import com.langfuse.client.core.LangfuseClientApiException;

LangfuseClient client = LangfuseClient.builder()
  .url("https://cloud.langfuse.com") // 🇪🇺 EU data region
  // Other Langfuse data regions:
  // .url("https://us.cloud.langfuse.com") // 🇺🇸 US
  // .url("https://jp.cloud.langfuse.com") // 🇯🇵 Japan
  // .url("https://hipaa.cloud.langfuse.com") // ⚕️ HIPAA
  // .url("http://localhost:3000") // 🏠 Local deployment
  .credentials("pk-lf-...", "sk-lf-...")
  .build();

try {
  PromptMetaListResponse prompts = client.prompts().list();
} catch (LangfuseClientApiException error) {
  System.out.println(error.getBody());
  System.out.println(error.getStatusCode());
}

API로 trace 수집

OpenTelemetry 엔드포인트가 trace 수집의 지원 경로입니다. 기존 Ingestion API는 deprecated이며 Langfuse Cloud에서 2026년 11월 16일(2026-11-16)에 sunset됩니다. 셀프 호스팅 v4에서는 기본 events_only 쓰기 모드로 실행하면 사용할 수 없습니다. 지금 OpenTelemetry 엔드포인트로 전환하세요. custom ingestion migration guide 를 따라 legacy 이벤트를 v4-ready OTEL 스팬으로 매핑하세요. 이 deprecation은 trace와 observation 이벤트에 적용됩니다. 현재 SDK 스코어 헬퍼는 같은 엔드포인트에 score-create 이벤트를 보내며, 이 이벤트는 컷오버 후에도 지원됩니다.

  • OpenTelemetry Traces Ingestion Endpoint 는 OTLP/HTTP 스펙을 구현해 trace 수집을 지원하며, Langfuse Observability에 네이티브 OpenTelemetry 통합을 제공합니다.
  • (2026-11-16부터 sunset) Ingestion API 는 API로 trace 수집을 허용합니다.

API로 데이터 조회

새 데이터 추출 워크플로우에는 아래의 고성능 read API를 사용하세요. 각각 cursor 페이지네이션과 선택적 필드 검색을 중심으로 설계되어 필요한 컬럼만 가져옵니다.

조회하려는 것 사용
행 단위 observations(spans, generations, events) Observations API v2
Score 데이터(평가, 주석, API 수집) Scores API v3
실험 실행과 아이템 Experiments API
집계 분석(비용, 사용량, 지연시간, 볼륨) Metrics API v2

Deprecated된 trace, observation, score, metrics read API는 Migration of deprecated APIs 에 마이그레이션 단계와 함께 문서화되어 있습니다. 각 요청을 빠르게 유지하려면 항상 제한된 시간 범위(예: fromStartTime/toStartTime)를 포함하세요.

Observations API v2

이 기능은 어디에서 쓸 수 있나요?

플랜 사용 가능 여부
Hobby 사용 가능
Core 사용 가능
Pro 사용 가능
Enterprise 사용 가능
Self Hosted Langfuse v4+

커스텀 워크플로우, 평가 파이프라인, 분석을 위해 observation 데이터(spans, generations, events)를 조회하세요. 집계 메트릭(총 비용, 토큰 수, 사용자/모델/기간별 그룹화된 trace 볼륨)을 위해서는 raw 행을 직접 가져와 집계하는 대신 Metrics API 를 사용하세요.

GET /api/public/v2/observations

데이터 가용성: 이전 SDK(langfuse-python < 4.7.0, langfuse-js < 5.4.0)나 x-langfuse-ingestion-version: 4를 보내지 않는 직접 OpenTelemetry exporter의 데이터는 v2 엔드포인트에서 최대 15분까지 지연될 수 있습니다. Python SDK v4.7.0+ 또는 JS/TS SDK v5.4.0+ 로 업그레이드하거나, OTEL span exporter에 그 헤더를 설정 하여 새 데이터를 실시간으로 보세요. 자세한 내용은 Versions & Compatibility 를 참고하세요.

셀프 호스팅 Langfuse v3에서는 v1 Observations API 를 대신 사용하세요. 셀프 호스팅 호환성 매트릭스 를 참고하세요.

v2 Observations API는 고성능 검색을 위해 재설계되어 쿼리당 Langfuse가 수행하는 작업을 최소화합니다. 전체 매개변수와 응답 스키마는 v2 Observations API reference 를 참고하세요.

이전 trace/observation 읽기에서 업그레이드

migration guide 는 모든 deprecated read 엔드포인트(/api/public/traces, /api/public/observations, /api/public/sessions, ...)를 매개변수 매핑과 before/after 예시와 함께 v2 대체품으로 매핑합니다. 각 요청을 제한하려면 항상 fromStartTime과 toStartTime을 포함하세요.

v2 Observations API는 전체 trace 객체가 아니라 observation 행을 반환합니다. trace 활동을 재구성해야 할 때는 traceId로 행을 그룹화하고, traceName, traceRelease, traceVersion 같은 trace 수준 차원의 집계 보고에는 Metrics API v2 를 사용하세요. v2에는 get-by-id 라우트가 없습니다. 단일 observation 조회는 대신 id 컬럼에 URL-인코딩된 filter 조건을 전달하세요.

논리적 루트 observations

v2 API는 물리적 부모 관계와 논리적 루트 상태를 구분합니다:

  • parentObservationId는 물리적 부모 observation을 식별합니다. 빈 값은 물리적 부모가 없는 observations와 일치합니다.
  • isRootObservation은 observation에 물리적 부모가 없거나 SDK가 명시적으로 애플리케이션 루트로 표시했을 때 true입니다.

따라서 애플리케이션 루트 observation은 isRootObservation: true와 null이 아닌 parentObservationId를 가질 수 있습니다. 애플리케이션 루트가 필요하면 isRootObservation을, 물리적 observation 트리를 쿼리해야 하면 parentObservationId를 사용하세요.

논리적 루트 필터는 trace당 하나의 내보내진 애플리케이션 루트를 가정합니다. trace에 이 프로젝트의 내보내진 루트가 없다면(예: 루트가 다른 서비스에 있는 경우) isRootObservation = true가 일치하지 않습니다. 완전한 trace 개수가 필요하면 traceId로 그룹화하세요. 여러 일치 루트는 통합 문제를 나타냅니다.

선택적 필드 검색

v2 API는 모든 행의 모든 컬럼을 반환하는 대신, 쉼표 구분 문자열로 필요한 필드 그룹만 요청할 수 있게 합니다:

?fields=core,basic,usage
그룹 필드
core 항상 포함: id, traceId, startTime, endTime, projectId, parentObservationId, type
basic name, level, statusMessage, version, environment, bookmarked, public, userId, sessionId, isRootObservation
time completionStartTime, createdAt, updatedAt
io input, output
metadata metadata
model model, internalModelId, modelParameters
usage usageDetails, inputUsage, outputUsage, totalUsage, costDetails, inputCost, outputCost, totalCost, usagePricingTierName
prompt promptId, promptName, promptVersion
metrics latency, timeToFirstToken
trace_context tags, release, traceName

fields를 지정하지 않으면 기본적으로 core와 basic이 반환됩니다. 요청하지 않은 그룹의 필드는 null이 아니라 응답에서 없습니다(absent). 예외는 modelId, inputPrice, outputPrice, totalPrice로, 항상 존재하지만 model 그룹을 선택할 때만 채워집니다. inputPrice, outputPrice, totalPrice는 소수 정밀도를 보존하기 위해 문자열(예: "0.000005")로 반환되므로, 내 파이프라인에서 숫자 타입으로 캐스팅하세요.

v2 API는 또한 I/O를 항상 JSON으로 파싱하는 대신 raw 문자열로 반환합니다. 필요 시 내 파이프라인에서 파싱하세요. (parseIoAsJson 매개변수는 deprecated: 생략하거나 false로 설정하세요. true는 400을 반환합니다.)

Cursor 기반 페이지네이션

v2 API는 offset 기반 페이지 번호 대신 cursor로 페이지네이션하여 대용량 데이터셋에서 일관된 성능을 제공합니다:

  • limit 매개변수로 초기 요청을 보냅니다 (기본 50, 최대 1,000 — v1의 최대 100에서 증가).
  • 더 많은 결과가 있으면 응답의 meta 객체에 cursor가 포함됩니다.
  • 다음 요청의 cursor 매개변수로 이 cursor를 전달해 이어갑니다.
  • cursor가 더 이상 반환되지 않을 때까지(또는 meta.cursor가 null) 반복합니다 — 끝에 도달했습니다.

결과는 항상 startTime 내림차순(최신 우선)으로 정렬됩니다.

Langfuse Cloud에서 요청은 일반 조직 API rate limit에 포함됩니다(API limits FAQ 참고). 셀프 호스팅 인스턴스에는 강제 rate limit이 없습니다.

예시

특정 trace의 observations를 가져온 뒤 반환된 cursor로 페이지네이션:

# Fetch a page for one trace
curl \
  -H "Authorization: Basic *** AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/observations?fields=core,basic,usage&traceId=your-trace-id&limit=100"

# Response includes: "meta": { "cursor": "eyJsYXN0..." }
# Pass it back to fetch the next page
curl \
  -H "Authorization: Basic *** AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/observations?fields=core,basic,usage&traceId=your-trace-id&limit=100&cursor=eyJsYXN0..."

일급 쿼리 매개변수로 논리적 루트 필터링:

curl \
  -H "Authorization: Basic *** AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/observations?isRootObservation=true&fromStartTime=2025-12-15T00:00:00Z&toStartTime=2025-12-16T00:00:00Z"

고급 filter 매개변수는 불리언 =와 <> 연산자로 같은 필드를 지원합니다. 예: URL-인코딩된 JSON 값 [{"type":"boolean","column":"isRootObservation","operator":"=","value":true}].

Scores API v3

이 기능은 어디에서 쓸 수 있나요?

플랜 사용 가능 여부
Hobby 사용 가능
Core 사용 가능
Pro 사용 가능
Enterprise 사용 가능
Self Hosted Langfuse v3.179.0+

커스텀 워크플로우, 평가 파이프라인, 분석을 위해 score 데이터(평가, 주석, API 수집 점수)를 조회하세요. 집계 score 메트릭(예: trace 이름, 사용자, 기간별 그룹화된 평균 점수)은 Metrics API 를 대신 사용하세요.

GET /api/public/v3/scores

이 섹션은 점수 읽기를 다룹니다. 점수는 POST /api/public/scores 또는 SDK 헬퍼로 생성됩니다(scores via API/SDK 참고). 전체 매개변수/응답 스키마는 v3 Scores API reference 를 참고하세요.

value 필드

모든 점수는 정확히 하나의 타입된 value를 담습니다. 그 타입은 점수의 dataType에 의해 결정됩니다:

dataType value 타입 비고
NUMERIC number
BOOLEAN boolean
CATEGORICAL string 카테고리
TEXT string
CORRECTION string 수정이 없으면 빈 문자열

내 파이프라인이 혼합 점수 타입을 처리하면 dataType으로 분기하세요.

선택적 필드 검색

응답은 항상 슬림한 코어(id, projectId, name, value, dataType, source, timestamp, environment, createdAt, updatedAt)를 포함합니다. 쉼표 구분 fields 매개변수로 추가 그룹에 opt-in하세요(알 수 없는 그룹 이름은 HTTP 400 반환):

?fields=details,subject,annotation
그룹 필드
core 항상 포함(위 참고)
details comment, configId, metadata
subject subject (점수가 연결된 엔터티, 아래 참고)
annotation authorUserId, queueId

subject 객체

모든 점수는 정확히 하나의 엔터티에 연결됩니다. subject 필드 그룹을 요청해 어떤 것인지 확인하세요. kind로 구분됩니다:

{ "kind": "observation", "id": "obs-1", "traceId": "trace-1" }
  • kind: "trace": id는 trace ID
  • kind: "observation": id는 observation ID. 부모 traceId 포함
  • kind: "session": id는 세션 ID
  • kind: "experiment": id는 dataset run ID

필터링

  • 다중 값 필터: 대부분의 필터는 쉼표 구분 목록을 허용합니다 (id, name, source, dataType, environment, configId, queueId, authorUserId, traceId, sessionId, observationId, experimentId). 한 매개변수 안의 값은 OR, 매개변수 간에는 AND: name=hallucination,toxicity&source=EVAL은 hallucination 또는 toxicity라는 이름의 eval 점수를 반환.
  • 값 필터: 정확 일치에는 value(NUMERIC, BOOLEAN, CATEGORICAL의 단일 dataType 필요, 쉼표 구분), 포함 숫자 범위에는 valueMin/valueMax(dataType=NUMERIC 필요).
  • 상호 배타성: traceId, sessionId, experimentId는 상호 배타적입니다. observationId는 observation ID가 trace로 범위 지정되므로 traceId를 요구합니다.
  • 대소문자 무시 enum: source와 dataType은 어떤 대소문자도 받습니다(numeric과 NUMERIC 동일).
  • 타임스탬프 경계: fromTimestamp는 포함, toTimestamp는 배타.

잘못된 필터 조합은 조용히 무시되는 대신 HTTP 400으로 거부됩니다. 페이지네이션은 cursor 기반(기본 50, 최대 100)이며 반환된 meta.cursor를 같은 필터 매개변수와 함께 전달해 다음 페이지를 가져옵니다. 데이터 웨어하우스로 반복 전체 내보내기를 하려면 API를 페이지네이션하는 대신 scheduled blob storage export 를 사용하세요.

예시

숫자 범위 안의 실패 eval 가져오기:

curl \
  -H "Authorization: Basic *** AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v3/scores?name=hallucination,toxicity&dataType=NUMERIC&valueMax=0.5"

특정 traces의 점수, 연결된 대상 포함:

curl \
  -H "Authorization: Basic *** AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v3/scores?traceId=trace-1,trace-2&fields=details,subject"

생성된 SDK 클라이언트는 같은 엔드포인트를 노출합니다(Python api.scores_v3, JS/TS api.scoresV3). Query via SDKs 참고. 점수 생성은 별도 SDK 헬퍼(예: Python create_score)를 사용합니다. 이 클라이언트는 읽기용입니다.

Experiments API

이 기능은 어디에서 쓸 수 있나요?

플랜 사용 가능 여부
Hobby 사용 가능
Core 사용 가능
Pro 사용 가능
Enterprise 사용 가능
Self Hosted Langfuse v4+

분석, 평가 파이프라인, 노트북, CI/CD 워크플로우를 위해 실험 데이터를 조회하세요. 실험은 테스트 데이터에 대한 내 애플리케이션의 실행입니다. 각 실험 아이템은 하나의 입력, 그 expected output, 그리고 내 애플리케이션이 만든 실제 출력을 나타냅니다. 완전한 요청/응답 계약은 Experiments API reference 를 참고하세요.

원하는 것 사용
실험 실행 및 실험 데이터 수집 Experiment runner SDK 또는 Experiments via OpenTelemetry
실험 실행과 요약 목록 GET /api/public/experiments?fromStartTime=2026-01-01T00:00:00Z
실험 아이템과 입력, 출력, expected outputs, metadata, scores 조회 GET /api/public/experiment-items?fromStartTime=2026-01-01T00:00:00Z
아이템의 완전한 trace/observation 트리 조회 Observations API v2, 아이템의 traceId 사용
평가 점수를 독립적으로 조회 Scores API v3

실험 엔드포인트는 필터링, cursor 페이지네이션, 선택적 응답 필드를 지원합니다. 사용 가능한 필터와 응답 필드는 Experiments API reference 를 참고하세요.

실험 수준 점수는 전체 실행을 요약하고, 아이템 수준·trace 수준 점수는 개별 실험 아이템을 평가합니다. Experiments API는 두 수준을 해당 응답에 반환합니다. 점수가 주로 쿼리해야 하는 데이터라면 Scores API v3 가 유용합니다. 데이터셋, 실험, 아이템, traces, observations, scores의 관계를 이해하려면 Experiments data model 을 참고하세요.

대안(Alternatives)

다음으로도 데이터를 내보낼 수 있습니다:

  • Query via SDKs — 같은 엔드포인트의 타입화된 Python/JS/TS 래퍼
  • UI — Langfuse UI에서 수동 배치 내보내기
  • Blob Storage — 클라우드 스토리지로 예약 자동 내보내기

FAQ

관련 API 리소스

더 알아보기 (Learn more)