Public API
Langfuse 是开放的,旨在通过自定义工作流和集成进行扩展。所有 Langfuse 数据和功能都可通过 API 获得。
Path
/api/public
Cloud US
https://us.cloud.langfuse.com/api/public
Cloud EU
https://cloud.langfuse.com/api/public
Cloud Japan
https://jp.cloud.langfuse.com/api/public
HIPAA US
https://hipaa.cloud.langfuse.com/api/public
参考:
- API Reference: https://api.reference.langfuse.com
- OpenAPI spec: https://cloud.langfuse.com/generated/api/openapi.yml
有 3 组不同的 API:
- 本页 -> 项目级 API:在项目内对 traces/evals/prompts/configuration 进行 CRUD
- 组织级 API:配置项目、用户(SCIM)和权限
- 实例管理 API:在自托管安装上管理组织
身份验证
使用 Basic Auth 对 API 进行身份验证。 API 密钥可在 Langfuse 项目设置中获得。
- 用户名:Langfuse Public Key
- 密码:Langfuse Secret Key
示例:
curl -u public-key:secret-key https://cloud.langfuse.com/api/public/projects
通过 SDK 访问
Langfuse Python SDK 和 JS/TS SDK 都提供了围绕我们公共 REST API 的强类型包装,以方便你使用。在两个 SDK 中,API 方法都可通过 Langfuse 客户端实例上的 api 属性访问。
你可以使用编辑器的 Intellisense 来探索 API 方法及其参数。
在 Python SDK v4 和 JS/TS SDK v5 中,高性能资源是默认值:
api.observations、api.metrics,以及——用于分数读取——api.scores_v3/api.scoresV3(api.scores,即 v2 读取,已弃用;参见已弃用 API 的迁移)。已弃用的 v1 资源移到了api.legacy.*下(Python:*_v1,JS/TS:*V1)。SDK 示例参见通过 SDK 查询。Observations API v2 和 Metrics API v2 在 Langfuse Cloud 和自托管 Langfuse v4 上可用。在自托管 Langfuse v3 上,请使用
api.legacy.*资源。参见版本与兼容性。
获取提示词时,请使用 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.get(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.*
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.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"
})
});
// explore more endpoints via Intellisense
langfuse.api.*
通过将以下内容添加到你的 pom.xml 来安装 Langfuse:
<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 接入 Traces
OpenTelemetry 端点将在未来取代 Ingestion API。因此,强烈建议切换到 OpenTelemetry 端点进行 trace 接入。遵循自定义接入迁移指南,将旧版事件映射到 v4 就绪的 OTEL spans。
- OpenTelemetry Traces 接入端点实现了用于 trace 接入的 OTLP/HTTP 规范,为 Langfuse 可观测性提供原生 OpenTelemetry 集成。
- (已弃用)Ingestion API允许使用 API 进行 trace 接入。
通过 API 检索数据
对于新的数据提取工作流,请使用高性能数据 API:
- Observations API v2 - 从 Langfuse 检索 observation 数据(spans、generations、events),用于自定义工作流、评估流水线和分析。
- Scores API v3 - 检索分数数据(评估、标注和通过 API 接入的分数),带类型化的 value 字段和基于游标的分页。
- Metrics API v2 - 从你的 Langfuse 数据检索聚合分析和指标。
已弃用的 trace、observation、score 和 metrics 读取 API,连同迁移步骤,记录在已弃用 API 的迁移中。
替代方案
你也可以通过以下方式导出数据: