Public API

Langfuse is open and meant to be extended via custom workflows and integrations. All Langfuse data and features are available via the API.

/api/public

https://us.cloud.langfuse.com/api/public

https://cloud.langfuse.com/api/public

References:

• API Reference: https://api.reference.langfuse.com
• OpenAPI spec: https://cloud.langfuse.com/generated/api/openapi.yml
• Postman collection: https://cloud.langfuse.com/generated/postman/collection.json

Authentication

Authenticate with the API using Basic Auth. The API keys are available in the Langfuse project settings.

• Username: Langfuse Public Key
• Password: Langfuse Secret Key

Example:

curl -u public-key:secret-key https://cloud.langfuse.com/api/public/projects

Access via SDKs

Both the Langfuse Python SDK and the JS/TS SDK provide a strongly-typed wrapper around our public REST API for your convenience. The API methods are accessible via the api property on the Langfuse client instance in both SDKs.

You can use your editor’s Intellisense to explore the API methods and their parameters.

from langfuse import Langfuse
 
langfuse = Langfuse()
...
# fetch a trace
langfuse.api.trace.get(trace_id)
 
# async client via asyncio
await langfuse.async_api.trace(trace_id)
 
# explore more endpoints via Intellisense
langfuse.api.*
await langfuse.async_api.*

from langfuse.decorators import langfuse_context
 
# fetch a trace
langfuse_context.client_instance.api.trace.get(trace_id)
 
# async client via asyncio
await langfuse_context.client_instance.async_api.trace(trace_id)
 
# explore more endpoints via Intellisense
langfuse_context.client_instance.api.*
await langfuse_context.client_instance.async_api.*

import { Langfuse } from "langfuse"
 
const langfuse = new Langfuse()
...
// fetch a trace
await langfuse.api.traceGet(traceId)
 
// explore more endpoints via Intellisense
langfuse.api.*

<dependencies>
  <dependency>
    <groupId>com.langfuse</groupId>
    <artifactId>langfuse-java</artifactId>
    <version>0.0.1-SNAPSHOT</version>
  </dependency>
</dependencies>
 
<repositories>
  <repository>
    <id>github</id>
    <name>GitHub Package Registry</name>
    <url>https://maven.pkg.github.com/langfuse/langfuse-java</url>
  </repository>
</repositories>

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.prompts.types.PromptMetaListResponse;
import com.langfuse.client.core.LangfuseClientApiException;
 
LangfuseClient client = LangfuseClient.builder()
  .url("https://cloud.langfuse.com") // 🇪🇺 EU data region
  // .url("https://us.cloud.langfuse.com") // 🇺🇸 US data region
  // .url("http://localhost:3000") // 🏠 Local deployment
  .credentials("pk-lf-...", "sk-lf-...")
  .build();
 
try {
  PromptMetaListResponse prompts = client.prompts().list();
} catch (LangfuseClientApiException error) {
  System.out.println(error.getBody());
  System.out.println(error.getStatusCode());
}

Ingest Data via the API

If you want to use tracing via the API, such as to build your own Langfuse client implementation, this is the only API route you need to implement:

POST /api/public/ingestion

API Reference: POST /api/public/ingestion

Within each batch, there can be multiple events. Each event has a type, an id, a timestamp, metadata and a body. Internally, we refer to this as the “event envelope” as it tells us something about the event but not the trace. We use the event id within this envelope to deduplicate messages to avoid processing the same event twice, i.e. the event id should be unique per request. The event.body.id is the ID of the actual trace and will be used for updates and will be visible within the Langfuse App. I.e. if you want to update a trace, you’d use the same body id, but separate event IDs.

Notes:

• Introduction to data model: https://langfuse.com/docs/tracing-data-model
• Batch sizes are limited to 3.5 MB in total. You need to adjust the number of events per batch accordingly.
• The API does not return a 4xx status code for input errors. Instead, it responds with a 207 status code, which includes a list of the encountered errors.

Organization-Key Scoped API Routes

Langfuse is open and meant to be extended via custom workflows and integrations. You can use these endpoints to automate project and user management on your Langfuse organization.

All applicable endpoints are marked with (requires organization-scoped API key). Those include the following routes.

• POST /api/public/projects
• PUT /api/public/projects/{projectId}
• DELETE /api/public/projects/{projectId}
• GET /api/public/projects/{projectId}/apiKeys
• POST /api/public/projects/{projectId}/apiKeys
• DELETE /api/public/projects/{projectId}/apiKeys/{apiKeyId}
• PUT /api/public/organizations/memberships
• GET /api/public/organizations/memberships
• PUT /api/public/projects/{projectId}/memberships
• DELETE /api/public/projects/{projectId}/memberships

In addition, we implement the following SCIM compliant endpoints. Use /api/public/scim as the base URI for them.

• GET /ServiceProviderConfig
• GET /ResourceTypes
• GET /Schemas
• GET /Users
• POST /Users
• GET /Users/{id}
• DELETE /Users/{id}

Authentication

Authenticate with the API using Basic Auth. Organization scoped API keys can be created via the Organization Management API. In the future, they will be available within the Organization Settings page within Langfuse.

Example:

curl -u public-key:secret-key https://cloud.langfuse.com/api/public/projects/{projectId}/apiKeys

User Management

To create a new user within Langfuse, you can use the SCIM-style endpoints and POST /Users. This will create a new user if the email does not exist yet. Then it will add the user to the organization with role NONE.

Afterward, the role can be updated using the memberships endpoints either on an organization or a project level.

To remove a user from an organization, call the DELETE /Users/{id} endpoint. This will not delete the user itself, only its membership with the organization.

You can either supply an initial password for users via the API and share it with them, or use Single Sign-On (SSO) to authenticate users. In the latter case, you need to configure AUTH_<PROVIDER>_ALLOW_ACCOUNT_LINKING for your SSO provider to ensure that the user accounts are linked correctly SSO Docs.