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.

When fetching prompts, please use the get_prompt (Python) / getPrompt (JS/TS) methods on the Langfuse client to benefit from client-side caching, automatic retries, and fallbacks.

When using the low-level SDK:

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.*

You can also access the Langfuse client instance when using the decorator-based integration:

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.*

Install Langfuse by adding the following to your pom.xml:

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

Instantiate and use the Java SDK via:

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.

Public API

Authentication

Access via SDKs

Ingest Data via the API

Was this page useful?

Questions? We're here to help

Subscribe to updates