langfuse-api

Langfuse API

REST API を介して Langfuse を操作できるよう、ユーザーを支援します。

使用するタイミング

• トレースをクエリまたはエクスポートしたい場合
• プロンプトをプログラムから管理したい場合
• データセットまたはデータセット項目を作成・更新したい場合
• スコアを取得または作成したい場合
• プロジェクトまたは API キーを管理したい場合
• その他、Langfuse API を操作する場合

ワークフロー

1. 認証情報を確認する

API を呼び出す前に、認証情報が利用可能かどうかを確認します。

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

設定されていない場合は、ユーザーに確認します。

• 「Langfuse の API 認証情報が必要です。Langfuse UI の Settings → API Keys で確認できます。」
• 「どの Langfuse ホストを使用していますか？（cloud.langfuse.com、us.cloud.langfuse.com、eu.cloud.langfuse.com、またはセルフホストの URL）」

2. 最新の API リファレンスを取得する

API を呼び出す前に、必ず最新の API リファレンスを取得してください。 API には新しいエンドポイントが追加されたり、パラメーターが変更されたりしている可能性があります。

取得先：https://api.reference.langfuse.com

ユーザーのリクエストに必要なエンドポイントを確認します。リファレンスには次の情報が含まれています。

• 利用可能なすべてのエンドポイント
• 必須および任意のパラメーター
• リクエスト／レスポンスのスキーマ
• 認証の詳細

3. API を呼び出す

認証： LANGFUSE_PUBLIC_KEY をユーザー名、LANGFUSE_SECRET_KEY をパスワードとして使用する Basic Auth。

ベース URL： {LANGFUSE_HOST}/api/public

例：

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

4. ページネーションを処理する

多くのエンドポイントはページ分割された結果を返します。次の点を確認します。

• page と limit パラメーター
• レスポンス内の meta.totalItems と meta.totalPages
• ユーザーがすべての結果を必要とする場合は、繰り返し処理する

よくある使用例

ユーザーのリクエスト	確認するエンドポイント
「最近のトレースを取得して」	GET /traces
「先週のトレースをエクスポートして」	日付フィルターを指定して GET /traces
「特定のプロンプトを取得して」	GET /prompts/{name}
「データセットを作成して」	POST /datasets
「データセットに項目を追加して」	POST /dataset-items
「トレースのスコアを取得して」	traceId フィルターを指定して GET /scores
「すべてのプロンプトを一覧表示して」	GET /prompts

重要な注意事項

• 常に最新のドキュメントを取得する - API に関するキャッシュ済みの知識に頼らないでください
• レート制限を確認する - API にはレート制限があります。429 レスポンスを適切に処理してください
• レスポンスを検証する - データを処理する前にエラーがないか確認してください
• 大規模なエクスポート - 大量のデータを扱う場合は、ページネーションを使用し、ファイルへのストリーミングを検討してください

OpenAPI 仕様

プログラムからのアクセスや型の生成には、次を使用します。

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