tessl/npm-langfuse

Observability and analytics platform for LLM applications with hierarchical tracing, prompt management, dataset operations, and OpenAI integration

Overview

Eval results

Files

Public API

Name: tessl/npm-langfuse
Author: tessl

Direct access to Langfuse REST API endpoints through the api property. The public API client provides low-level access to all Langfuse backend operations, including operations not exposed through convenience methods.

Capabilities

Accessing the API Client

The api property provides access to the auto-generated REST API client.

class Langfuse {
  /** Public API client for direct API access */
  api: LangfusePublicApi<null>["api"];
}

Usage Example:

import { Langfuse } from 'langfuse';

const langfuse = new Langfuse({
  publicKey: 'pk-lf-...',
  secretKey: 'sk-lf-...'
});

// Access API groups
const traces = await langfuse.api.traces.list({ page: 1, limit: 10 });
const models = await langfuse.api.models.list();
const scores = await langfuse.api.score.list({ page: 1 });

API Groups

The API client is organized into functional groups. All methods return promises and follow REST conventions.

Traces API

Operations for managing traces.

interface TracesAPI {
  /** List traces with filtering */
  list(query?: GetLangfuseTracesQuery): Promise<GetLangfuseTracesResponse>;

  /** Get a specific trace by ID */
  get(traceId: string): Promise<{ data: GetLangfuseTraceResponse }>;
}

Usage Example:

// List traces
const traces = await langfuse.api.traces.list({
  page: 1,
  limit: 50,
  userId: 'user-123',
  tags: ['production'],
  fromTimestamp: '2024-01-01T00:00:00Z'
});

// Get specific trace
const trace = await langfuse.api.traces.get('trace-id-123');

Observations API

Operations for managing observations (spans, generations, events).

interface ObservationsAPI {
  /** List observations with filtering */
  list(query?: GetLangfuseObservationsQuery): Promise<GetLangfuseObservationsResponse>;

  /** Get a specific observation by ID */
  get(observationId: string): Promise<{ data: GetLangfuseObservationResponse }>;
}

Usage Example:

// List all generations
const generations = await langfuse.api.observations.list({
  type: 'GENERATION',
  page: 1,
  limit: 100
});

// Get specific observation
const observation = await langfuse.api.observations.get('obs-id-123');

Sessions API

Operations for managing sessions.

interface SessionsAPI {
  /** List sessions with filtering */
  list(query?: GetLangfuseSessionsQuery): Promise<GetLangfuseSessionsResponse>;
}

Usage Example:

// List recent sessions
const sessions = await langfuse.api.sessions.list({
  page: 1,
  limit: 50,
  fromTimestamp: '2024-01-01T00:00:00Z'
});

Dataset API

Operations for managing datasets.

interface DatasetAPI {
  /** List datasets */
  list(): Promise<ApiPaginatedDatasets>;

  /** Get a specific dataset */
  get(datasetName: string): Promise<{ data: GetLangfuseDatasetResponse }>;

  /** Create a dataset */
  create(body: CreateLangfuseDatasetBody): Promise<CreateLangfuseDatasetResponse>;
}

Usage Example:

// List all datasets
const datasets = await langfuse.api.dataset.list();

// Get specific dataset
const dataset = await langfuse.api.dataset.get('eval-dataset');

// Create new dataset
const newDataset = await langfuse.api.dataset.create({
  name: 'new-eval-dataset',
  description: 'Evaluation dataset for Q1 2024'
});

Dataset Items API

Operations for managing dataset items.

interface DatasetItemsAPI {
  /** List items for a dataset */
  list(datasetName: string, query?: any): Promise<GetLangfuseDatasetItemsResponse>;

  /** Get a specific dataset item */
  get(itemId: string): Promise<CreateLangfuseDatasetItemResponse>;

  /** Create a dataset item */
  create(body: CreateLangfuseDatasetItemBody): Promise<CreateLangfuseDatasetItemResponse>;
}

Usage Example:

// List dataset items
const items = await langfuse.api.datasetItems.list('eval-dataset', {
  page: 1,
  limit: 100
});

// Get specific item
const item = await langfuse.api.datasetItems.get('item-id-123');

// Create item
const newItem = await langfuse.api.datasetItems.create({
  datasetName: 'eval-dataset',
  input: { question: 'What is AI?' },
  expectedOutput: { answer: 'Artificial Intelligence...' }
});

Dataset Run Items API

Operations for managing dataset run items.

interface DatasetRunItemsAPI {
  /** Create a dataset run item */
  create(body: CreateLangfuseDatasetRunItemBody): Promise<CreateLangfuseDatasetRunItemResponse>;
}

Usage Example:

// Link trace to dataset item
const runItem = await langfuse.api.datasetRunItems.create({
  runName: 'gpt4-evaluation',
  datasetItemId: 'item-123',
  traceId: 'trace-456',
  observationId: 'obs-789'
});

Prompts API

Operations for managing prompts.

interface PromptsAPI {
  /** List prompt versions */
  list(params: { name: string; version?: number; label?: string }): Promise<any>;

  /** Get a specific prompt */
  get(name: string, version?: number, label?: string): Promise<LangfusePromptRecord>;

  /** Create a prompt */
  create(body: CreateTextPromptBody | CreateChatPromptBody): Promise<CreateLangfusePromptResponse>;
}

Usage Example:

// List prompt versions
const versions = await langfuse.api.prompts.list({
  name: 'chat-template'
});

// Get specific version
const prompt = await langfuse.api.prompts.get('chat-template', 3);

// Create new prompt
const newPrompt = await langfuse.api.prompts.create({
  name: 'new-template',
  prompt: 'Hello {{name}}!',
  labels: ['production']
});

Score API

Operations for managing scores.

interface ScoreAPI {
  /** List scores */
  list(query?: any): Promise<ApiGetScoresResponse>;

  /** Create a score */
  create(body: CreateLangfuseScoreBody): Promise<any>;
}

Usage Example:

// List scores
const scores = await langfuse.api.score.list({
  page: 1,
  limit: 50,
  name: 'quality'
});

// Create score
const score = await langfuse.api.score.create({
  traceId: 'trace-123',
  name: 'accuracy',
  value: 0.95
});

Score Configs API

Operations for managing score configurations.

interface ScoreConfigsAPI {
  /** List score configurations */
  list(): Promise<ApiScoreConfigs>;

  /** Create score configuration */
  create(body: ApiCreateScoreConfigRequest): Promise<ApiScoreConfig>;
}

Usage Example:

// List score configs
const configs = await langfuse.api.scoreConfigs.list();

// Create score config
const config = await langfuse.api.scoreConfigs.create({
  name: 'quality',
  dataType: 'NUMERIC',
  minValue: 0,
  maxValue: 1
});

Models API

Operations for managing models.

interface ModelsAPI {
  /** List models */
  list(): Promise<ApiPaginatedModels>;

  /** Create a model */
  create(body: ApiCreateModelRequest): Promise<ApiModel>;
}

Usage Example:

// List available models
const models = await langfuse.api.models.list();

// Register custom model with pricing
const model = await langfuse.api.models.create({
  modelName: 'custom-gpt-4',
  matchPattern: 'custom-gpt-4.*',
  unit: 'TOKENS',
  inputPrice: 0.00003,
  outputPrice: 0.00006
});

Media API

Operations for managing media content.

interface MediaAPI {
  /** Get media metadata */
  get(mediaId: string): Promise<GetMediaResponse>;

  /** Get upload URL for media */
  getUploadUrl(body: ApiGetMediaUploadUrlRequest): Promise<ApiGetMediaUploadUrlResponse>;

  /** Update media metadata */
  patch(mediaId: string, body: ApiPatchMediaBody): Promise<any>;
}

Usage Example:

// Get media info
const media = await langfuse.api.media.get('media-id-123');

// Get upload URL
const uploadUrl = await langfuse.api.media.getUploadUrl({
  contentType: 'image/png',
  contentLength: 12345
});

// Upload media to URL
await fetch(uploadUrl.uploadUrl, {
  method: 'PUT',
  body: imageBuffer,
  headers: { 'Content-Type': 'image/png' }
});

// Update media metadata
await langfuse.api.media.patch('media-id-123', {
  metadata: { description: 'User uploaded image' }
});

Comments API

Operations for managing comments (annotations).

interface CommentsAPI {
  /** List comments */
  list(query: { objectType: string; objectId: string }): Promise<ApiGetCommentsResponse>;

  /** Create a comment */
  create(body: ApiCreateCommentRequest): Promise<ApiCreateCommentResponse>;
}

Usage Example:

// List comments for a trace
const comments = await langfuse.api.comments.list({
  objectType: 'TRACE',
  objectId: 'trace-id-123'
});

// Create comment
const comment = await langfuse.api.comments.create({
  objectType: 'TRACE',
  objectId: 'trace-id-123',
  content: 'This trace shows excellent performance'
});

Annotation Queues API

Operations for managing annotation queues (enterprise feature).

interface AnnotationQueuesAPI {
  /** List annotation queues */
  list(): Promise<ApiPaginatedAnnotationQueues>;

  /** List items in a queue */
  listItems(queueId: string): Promise<ApiPaginatedAnnotationQueueItems>;

  /** Add item to queue */
  addItem(body: ApiCreateAnnotationQueueItemRequest): Promise<any>;

  /** Update queue item */
  updateItem(itemId: string, body: ApiUpdateAnnotationQueueItemRequest): Promise<any>;
}

Usage Example:

// List queues
const queues = await langfuse.api.annotationQueues.list();

// Get items in queue
const items = await langfuse.api.annotationQueues.listItems('queue-id-123');

// Add trace to annotation queue
await langfuse.api.annotationQueues.addItem({
  queueId: 'queue-id-123',
  objectType: 'TRACE',
  objectId: 'trace-id-456'
});

Projects API

Operations for managing projects.

interface ProjectsAPI {
  /** List projects */
  list(): Promise<ApiProjects>;

  /** Get project details */
  get(projectId: string): Promise<ApiProject>;
}

Usage Example:

// List all projects
const projects = await langfuse.api.projects.list();

// Get specific project
const project = await langfuse.api.projects.get('project-id-123');

Ingestion API

Low-level event ingestion endpoint.

interface IngestionAPI {
  /** Batch ingest events */
  batch(body: { batch: ApiIngestionEvent[] }): Promise<ApiIngestionResponse>;
}

Usage Example:

// Batch ingest events (advanced usage)
const response = await langfuse.api.ingestion.batch({
  batch: [
    {
      type: 'trace-create',
      id: 'trace-123',
      timestamp: new Date().toISOString(),
      body: {
        id: 'trace-123',
        name: 'my-trace'
      }
    }
  ]
});

Health and Metrics API

Health check and metrics endpoints.

interface HealthAPI {
  /** Health check */
  check(): Promise<ApiHealthResponse>;
}

interface MetricsAPI {
  /** Get metrics */
  get(): Promise<ApiMetricsResponse>;
}

Usage Example:

// Health check
const health = await langfuse.api.health.check();
console.log(health.status); // "ok"

// Get metrics
const metrics = await langfuse.api.metrics.get();

Complete Public API Example

import { Langfuse } from 'langfuse';

const langfuse = new Langfuse({
  publicKey: 'pk-lf-...',
  secretKey: 'sk-lf-...'
});

// Fetch traces from the last 7 days
const oneWeekAgo = new Date();
oneWeekAgo.setDate(oneWeekAgo.getDate() - 7);

const traces = await langfuse.api.traces.list({
  page: 1,
  limit: 100,
  fromTimestamp: oneWeekAgo.toISOString(),
  tags: ['production']
});

// Analyze each trace
for (const trace of traces.data) {
  // Get full trace details
  const fullTrace = await langfuse.api.traces.get(trace.id);

  // Get observations for this trace
  const observations = await langfuse.api.observations.list({
    traceId: trace.id,
    type: 'GENERATION'
  });

  // Calculate average quality score
  const scores = await langfuse.api.score.list({
    traceId: trace.id,
    name: 'quality'
  });

  const avgScore = scores.data.reduce((sum, s) => sum + Number(s.value), 0) / scores.data.length;

  // Add comment if quality is low
  if (avgScore < 0.5) {
    await langfuse.api.comments.create({
      objectType: 'TRACE',
      objectId: trace.id,
      content: `Low quality trace: avg score ${avgScore.toFixed(2)}`
    });

    // Add to annotation queue for review
    await langfuse.api.annotationQueues.addItem({
      queueId: 'review-queue',
      objectType: 'TRACE',
      objectId: trace.id
    });
  }
}

// Get all datasets
const datasets = await langfuse.api.dataset.list();

// For each dataset, check completeness
for (const dataset of datasets.data) {
  const items = await langfuse.api.datasetItems.list(dataset.name, {
    page: 1,
    limit: 1000
  });

  console.log(`Dataset ${dataset.name}: ${items.data.length} items`);

  // Check for items without expected output
  const incomplete = items.data.filter(item => !item.expectedOutput);

  if (incomplete.length > 0) {
    console.log(`  ${incomplete.length} items missing expected output`);
  }
}

// List all available models and their pricing
const models = await langfuse.api.models.list();

for (const model of models.data) {
  console.log(`${model.modelName}:`);
  console.log(`  Input: $${model.inputPrice}/1k ${model.unit}`);
  console.log(`  Output: $${model.outputPrice}/1k ${model.unit}`);
}

// Health check
const health = await langfuse.api.health.check();
console.log('Langfuse status:', health.status);

API Types

The public API includes 190+ auto-generated TypeScript types from the OpenAPI specification. Key type categories include:

Trace Types: ApiTrace, ApiTraceWithDetails, ApiTraceWithFullDetails, ApiTraceBody
Observation Types: ApiObservation, ApiObservationsView, ApiObservationType, ApiObservationLevel
Score Types: ApiScore, ApiScoreConfig, ApiScoreDataType, ApiScoreSource
Dataset Types: ApiDataset, ApiDatasetItem, ApiDatasetRun, ApiDatasetRunItem
Prompt Types: ApiPrompt, ApiTextPrompt, ApiChatPrompt, ApiPromptMeta
Model Types: ApiModel, ApiModelPrice, ApiModelUsageUnit
Media Types: ApiMediaContentType, ApiGetMediaResponse, ApiGetMediaUploadUrlResponse
Session Types: ApiSession, ApiSessionWithTraces
Comment Types: ApiComment, ApiCommentObjectType
Annotation Types: ApiAnnotationQueue, ApiAnnotationQueueItem, ApiAnnotationQueueStatus
Ingestion Types: ApiIngestionEvent, ApiIngestionResponse, ApiIngestionSuccess, ApiIngestionError
Usage Types: ApiUsage, ApiUsageDetails, ApiOpenAIUsage
Pagination Types: ApiPaginatedDatasets, ApiPaginatedDatasetItems, ApiPaginatedModels

All types are exported from the main package and can be imported:

import type {
  ApiTrace,
  ApiObservation,
  ApiScore,
  ApiDataset,
  ApiPrompt,
  ApiModel
} from 'langfuse';

Notes

The public API client is auto-generated from the OpenAPI specification and provides low-level access to all backend operations
Most common operations are available through higher-level convenience methods (e.g., langfuse.trace(), langfuse.getDataset())
Use the public API for advanced operations not exposed through convenience methods or for building custom integrations
All API methods return promises and should be awaited
API responses follow standard REST conventions with data and metadata structures
Rate limiting and error handling are automatically managed by the client