langfuse-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Langfuse API

Help users interact with Langfuse via the REST API.

帮助用户通过REST API与Langfuse进行交互。

When to Use

使用场景

User wants to query or export traces
User wants to manage prompts programmatically
User wants to create/update datasets or dataset items
User wants to fetch or create scores
User wants to manage projects or API keys
Any other Langfuse API interaction

用户想要查询或导出追踪记录
用户想要以编程方式管理提示词
用户想要创建/更新数据集或数据集条目
用户想要获取或创建评分
用户想要管理项目或API密钥
任何其他Langfuse API交互场景

Workflow

工作流程

1. Check Credentials

1. 检查凭证

Before making any API call, verify credentials are available:

bash

echo $LANGFUSE_PUBLIC_KEY   # pk-...
echo $LANGFUSE_SECRET_KEY   # sk-...
echo $LANGFUSE_HOST         # https://cloud.langfuse.com (or self-hosted/EU/US URL)

If not set, ask user:

"I need your Langfuse API credentials. You can find them in Settings → API Keys in the Langfuse UI."
"Which Langfuse host are you using? (cloud.langfuse.com, us.cloud.langfuse.com, eu.cloud.langfuse.com, or self-hosted URL)"

在进行任何API调用之前，验证是否已获取凭证：

bash

echo $LANGFUSE_PUBLIC_KEY   # pk-...
echo $LANGFUSE_SECRET_KEY   # sk-...
echo $LANGFUSE_HOST         # https://cloud.langfuse.com (或自托管/欧盟/美国区域URL)

如果未设置，询问用户：

"我需要您的Langfuse API凭证。您可以在Langfuse UI的设置→API密钥中找到它们。"
"您正在使用哪个Langfuse主机？(cloud.langfuse.com, us.cloud.langfuse.com, eu.cloud.langfuse.com，或自托管URL)"

2. Fetch Fresh API Reference

2. 获取最新API参考文档

Always fetch the current API reference before making calls. The API may have new endpoints or changed parameters.

Fetch: https://api.reference.langfuse.com

Look for the specific endpoint needed for the user's request. The reference contains:

All available endpoints
Required and optional parameters
Request/response schemas
Authentication details

在进行调用前，请始终获取当前的API参考文档。 API可能新增了端点或修改了参数。

获取地址：https://api.reference.langfuse.com

查找用户请求所需的特定端点。参考文档包含：

所有可用端点
必填和可选参数
请求/响应 schema
认证详情

3. Make the API Call

3. 发起API调用

Authentication: Basic Auth with

LANGFUSE_PUBLIC_KEY

as username and

LANGFUSE_SECRET_KEY

as password.

Base URL:

{LANGFUSE_HOST}/api/public

Example:

bash

curl -X GET "${LANGFUSE_HOST}/api/public/traces" \
  -u "${LANGFUSE_PUBLIC_KEY}:${LANGFUSE_SECRET_KEY}" \
  -H "Content-Type: application/json"

认证方式： 使用

LANGFUSE_PUBLIC_KEY

作为用户名，

LANGFUSE_SECRET_KEY

作为密码的Basic Auth认证。

基础URL：

{LANGFUSE_HOST}/api/public

示例：

bash

curl -X GET "${LANGFUSE_HOST}/api/public/traces" \
  -u "${LANGFUSE_PUBLIC_KEY}:${LANGFUSE_SECRET_KEY}" \
  -H "Content-Type: application/json"

4. Handle Pagination

4. 处理分页

Many endpoints return paginated results. Check for:

```
page
```
and
```
limit
```
parameters
```
meta.totalItems
```
and
```
meta.totalPages
```
in response
Iterate if user needs all results

许多端点返回分页结果。需要检查：

```
page
```
和
```
limit
```
参数
响应中的
```
meta.totalItems
```
和
```
meta.totalPages
```
如果用户需要所有结果，进行迭代查询

Common Use Cases

常见使用场景

User Request	Endpoint to Look Up
"Get my recent traces"	GET /traces
"Export traces from last week"	GET /traces with date filters
"Fetch a specific prompt"	GET /prompts/{name}
"Create a dataset"	POST /datasets
"Add items to dataset"	POST /dataset-items
"Get scores for a trace"	GET /scores with traceId filter
"List all prompts"	GET /prompts

用户请求	需查找的端点
"获取我最近的追踪记录"	GET /traces
"导出上周的追踪记录"	GET /traces（带日期过滤器）
"获取特定提示词"	GET /prompts/{name}
"创建数据集"	POST /datasets
"向数据集添加条目"	POST /dataset-items
"获取某条追踪记录的评分"	GET /scores（带traceId过滤器）
"列出所有提示词"	GET /prompts

Important Notes

重要注意事项

Always fetch fresh docs - Don't rely on cached knowledge of the API
Check rate limits - The API has rate limits; handle 429 responses
Validate responses - Check for errors before processing data
Large exports - For bulk data, use pagination and consider streaming to file

始终获取最新文档 - 不要依赖缓存的API知识
检查速率限制 - API有速率限制；需处理429响应
验证响应 - 在处理数据前检查是否存在错误
大文件导出 - 对于批量数据，使用分页并考虑流式传输到文件

OpenAPI Spec

OpenAPI 规范

For programmatic access or generating types:

https://cloud.langfuse.com/generated/api/openapi.yml

对于编程访问或生成类型定义：

https://cloud.langfuse.com/generated/api/openapi.yml