Langfuse JavaScript / TypeScript SDK

Most GET APIs from the SDK packages can be up to 10 minutes behind.

To achieve real-time data ingestion, you must use the OpenTelemetry path:

1. Use @langfuse/otel or any OTel exporter sending the header x-langfuse-ingestion-version: 4.
2. Query data using the Observations API v2 (GET /api/public/v2/observations) and the Metrics API v2.

Do not use GET /api/public/traces or api.traceList for real-time requirements.

To use the latest Langfuse instrumentation (v5+), do not install the unscoped langfuse package, as it is a deprecated v3 client. Instead, use the scoped OpenTelemetry-based packages for instrumentation and the client package for managing prompts, datasets, and scores.

For standard instrumentation, install the tracing and OpenTelemetry packages:

npm install @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node

Use @langfuse/tracing (specifically startActiveObservation or startObservation) combined with LangfuseSpanProcessor from @langfuse/otel to send data.

⚠️ Deprecation Warning

On Langfuse Cloud, Langfuse v3 is deprecated and these endpoints will be removed on November 16, 2026. In Langfuse v4, dataset runs are replaced by experiments. Use the /api/public/experiments endpoint instead. Self-hosted deployments are unaffected by this date but will lose access if they upgrade to Langfuse v4.

Methods:

• getRun(datasetName, runName): Get a specific dataset run and its items.
• getRuns(datasetName, request): Get a paginated list of runs for a dataset.
• deleteRun(datasetName, runName): Irreversibly delete a dataset run and all its items.

// Deprecated usage:
await client.datasets.getRun("datasetName", "runName");
await client.datasets.getRuns("datasetName");
await client.datasets.deleteRun("datasetName", "runName");

The Langfuse API uses several core types to represent the hierarchy of LLM observability data.

• Trace: Represents a single execution flow or request lifecycle.
• Observation: A child unit within a trace, typically representing a specific step like a tool call, an LLM generation, or a span.
• ObservationV2: An updated version of the observation schema.
• TraceWithDetails / TraceWithFullDetails: Specialized trace objects containing expanded metadata and nested observation data.
• ObservationLevel: An enum/type defining the depth or type of an observation (e.g., span, generation, event).

Scoring is used to evaluate traces and observations. The API provides several specialized score types:

• Score: The base type for an evaluation.
• NumericScore: For quantitative evaluations (e.g., 0.0 to 1.0).
• BooleanScore: For binary evaluations (true/false).
• CategoricalScore: For label-based evaluations (e.g., 'positive', 'negative').
• TextScore: For qualitative, text-based evaluations.
• CorrectionScore: Specifically for scores that represent a correction to an output.
• ScoreConfig: Defines how scores should be configured or applied.
• CreateScoreValue: The input type used when creating a new score.

The LangfuseAPIClient acts as a gateway to various specialized service clients. You access these resources through getter properties on the client instance. Each property returns a client dedicated to a specific domain (e.g., traces, prompts, datasets).

Available resource namespaces include:

• annotationQueues
• blobStorageIntegrations
• comments
• datasetItems / datasets / datasetRunItems
• evaluationRules / evaluators
• experiments
• feedback
• health
• ingestion
• llmConnections
• media
• metrics
• models
• observations
• opentelemetry
• organizations
• projects
• promptVersion / prompts
• scim
• scoreConfigs / scores / scoresV3
• sessions
• trace
• unstable

// Example of accessing different resource clients
const traces = client.trace;
const prompts = client.prompts;
const datasets = client.datasets;

The PromptManager class is the primary interface for managing prompt templates in Langfuse. It provides high-level methods to create, retrieve, update, and delete both text and chat prompts. It features built-in intelligent caching to optimize performance by returning fresh prompts immediately, returning expired prompts while refreshing them in the background, and supporting fallbacks if a fetch fails.

// The PromptManager is typically accessed via the langfuse client
// e.g., langfuse.prompt.get("my-prompt")

Langfuse provides types to manage user or conversation-level grouping:

• Session: Represents a logical grouping of traces, often used to track a single user interaction or a multi-turn conversation.
• SessionWithTraces: An extended session object that includes the associated traces within that session.

The ScoreManager class is responsible for creating, batching, and sending score events to the Langfuse API. It optimizes performance by automatically batching scores and flushing them based on a count threshold or a time interval.

Key features include:

• Automatic Batching: Scores are queued and sent in batches to optimize API usage.
• OpenTelemetry Integration: Methods to automatically extract traceId and observationId from active or provided OpenTelemetry spans.
• Lifecycle Management: Methods to manually flush() pending scores or shutdown() the manager gracefully before application exit.

// Conceptual usage pattern
langfuse.score.create({
  name: "quality",
  value: 0.85,
  traceId: "trace-123",
  comment: "High quality response"
});

await langfuse.score.flush();

A FetchedDataset is an enhanced version of the base Dataset type. When you fetch a dataset using the DatasetManager, the resulting object includes:

1. items: An array of DatasetItem objects. Each item is automatically 'hydrated' with mediaReferences, meaning any media stored in the item's fields is replaced with a LangfuseMediaReference object for easy access.
2. runExperiment: A method that allows you to run a batch of evaluations. This method abstracts away the manual process of iterating through items and linking them to traces, instead handling the execution of a task and the application of evaluators in a single workflow.

This pattern moves the developer from manual item management to a high-level 'experimentation' mental model.

The LangfuseClient provides high-level managers for specific domains of the Langfuse platform. Note that tracing/observability is NOT part of this client; for tracing, use @langfuse/tracing and @langfuse/otel.

Available Managers:

• langfuse.prompt: Manage prompts (fetch, cache, compile, and version).
• langfuse.dataset: Manage test datasets and link items to runs.
• langfuse.experiment: Run tasks and evaluators over datasets.
• langfuse.score: Create evaluation or feedback scores for traces and observations.
• langfuse.media: Upload and resolve media references.
• langfuse.api: Direct access to the underlying LangfuseAPIClient for advanced REST API operations.

For evaluation and benchmarking, Langfuse uses a dataset model:

• Dataset: A collection of inputs and expected outputs used for testing.
• DatasetItem: A single entry within a dataset, which can include DatasetItemMediaReference for multimedia content.
• DatasetRun: An execution instance where a dataset is run against a model or prompt to collect results.
• DatasetRunItem: An individual result within a specific DatasetRun.
• DatasetStatus: Represents the current state of a dataset.