CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-langfuse

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

public-api.mddocs/

Public API

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

docs

configuration.md

datasets.md

index.md

media.md

openai-integration.md

prompts.md

public-api.md

tracing.md

tile.json