Langfuse API

Help users interact with Langfuse via the REST API.

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

Workflow

1. Check Credentials

Before making any API call, verify credentials are available:

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)"

2. Fetch Fresh API Reference

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

3. Make the API Call

Authentication: Basic Auth with LANGFUSE_PUBLIC_KEY as username and LANGFUSE_SECRET_KEY as password.

Base URL: {LANGFUSE_HOST}/api/public

Example:

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

4. Handle Pagination

Many endpoints return paginated results. Check for:

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

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

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

OpenAPI Spec

For programmatic access or generating types:

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