Back to Details

langfuse-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Langfuse API

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 RequestEndpoint 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