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

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