CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-langfuse--core

Core functions and utilities for Langfuse packages including API client, logging, media handling, and OpenTelemetry tracing attributes

Overview
Eval results
Files

api-client.mddocs/

API Client and Core Concepts

The LangfuseAPIClient is the main entry point for interacting with the Langfuse observability platform. It provides type-safe access to 23 resource clients, authentication management, retry logic, and comprehensive error handling.

Capabilities

LangfuseAPIClient Class

Main API client providing lazy-loaded access to all Langfuse platform resources.

class LangfuseAPIClient {
  constructor(options: LangfuseAPIClient.Options);

  // Resource accessors (read-only getters)
  readonly annotationQueues: AnnotationQueues;
  readonly blobStorageIntegrations: BlobStorageIntegrations;
  readonly comments: Comments;
  readonly datasetItems: DatasetItems;
  readonly datasetRunItems: DatasetRunItems;
  readonly datasets: Datasets;
  readonly health: Health;
  readonly ingestion: Ingestion;
  readonly llmConnections: LlmConnections;
  readonly media: Media;
  readonly metrics: Metrics;
  readonly models: Models;
  readonly observations: Observations;
  readonly organizations: Organizations;
  readonly projects: Projects;
  readonly promptVersion: PromptVersion;
  readonly prompts: Prompts;
  readonly scim: Scim;
  readonly scoreConfigs: ScoreConfigs;
  readonly scoreV2: ScoreV2;
  readonly score: Score;
  readonly sessions: Sessions;
  readonly trace: Trace;
}

Import:

import { LangfuseAPIClient } from '@langfuse/core';

Constructor

Creates a new API client instance with authentication and configuration.

constructor(options: LangfuseAPIClient.Options)

interface Options {
  environment: core.Supplier<string>;
  baseUrl?: core.Supplier<string>;
  username?: core.Supplier<string | undefined>;
  password?: core.Supplier<string | undefined>;
  xLangfuseSdkName?: core.Supplier<string | undefined>;
  xLangfuseSdkVersion?: core.Supplier<string | undefined>;
  xLangfusePublicKey?: core.Supplier<string | undefined>;
  headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
}

type Supplier<T> = T | (() => T);

Parameters:

  • options.environment - Base API URL (e.g., 'https://cloud.langfuse.com')
  • options.baseUrl - Alternative to environment for specifying base URL
  • options.username - Public API key (used as Basic Auth username)
  • options.password - Secret API key (used as Basic Auth password)
  • options.xLangfuseSdkName - SDK identifier (e.g., 'javascript')
  • options.xLangfuseSdkVersion - SDK version (e.g., '4.2.0')
  • options.xLangfusePublicKey - Public key for request headers
  • options.headers - Additional custom headers for all requests

Usage Example:

import { LangfuseAPIClient, LANGFUSE_SDK_NAME, LANGFUSE_SDK_VERSION } from '@langfuse/core';

// Basic initialization
const client = new LangfuseAPIClient({
  environment: 'https://cloud.langfuse.com',
  username: 'pk-lf-...',
  password: 'sk-lf-...'
});

// With all options
const client = new LangfuseAPIClient({
  environment: 'https://cloud.langfuse.com',
  username: process.env.LANGFUSE_PUBLIC_KEY,
  password: process.env.LANGFUSE_SECRET_KEY,
  xLangfuseSdkName: LANGFUSE_SDK_NAME,
  xLangfuseSdkVersion: LANGFUSE_SDK_VERSION,
  xLangfusePublicKey: process.env.LANGFUSE_PUBLIC_KEY,
  headers: {
    'User-Agent': 'my-app/1.0.0'
  }
});

// Access resources
const trace = await client.trace.get('trace-id');
const prompts = await client.prompts.list();

Resource Accessors

The client exposes 23 resource clients as read-only properties. These are lazily instantiated on first access.

Core Observability Resources:

// Traces - Complete trace lifecycle management
client.trace.get(traceId);
client.trace.list(filters);
client.trace.delete(traceId);

// Observations - Detailed observation queries
client.observations.list(filters);

// Sessions - Session grouping and analytics
client.sessions.list(filters);

Prompt Management Resources:

// Prompts - Version-controlled prompt templates
client.prompts.get(name, { version, label });
client.prompts.list(filters);
client.prompts.create(request);

// Prompt Versions - Update labels for specific version
client.promptVersion.update(promptName, version, { newLabels: ['production'] });

Evaluation Resources:

// Datasets - Test dataset management
client.datasets.list();
client.datasets.create(request);

// Dataset Items - Individual entries
client.datasetItems.create(request);

// Dataset Runs - Evaluation tracking
client.datasets.getRuns(datasetId);

// Scores - Score creation and queries
client.score.create(request);
client.scoreV2.list(filters);
client.scoreConfigs.list();

Platform Management Resources:

// Projects - Project administration
client.projects.list();

// Organizations - Multi-tenant management
client.organizations.list();

// Models - Model configuration
client.models.list();
client.models.create(request);

// Media - Media upload and retrieval
client.media.get(mediaId);
client.media.upload(request);

Additional Resources:

// Health - Health check endpoint
client.health.health();

// Metrics - Analytics and metrics
client.metrics.get(filters);

// Comments - Comment management
client.comments.create(request);
client.comments.list(filters);

// Annotation Queues - Annotation workflow
client.annotationQueues.list();
client.annotationQueues.create(request);

// LLM Connections - LLM integration management
client.llmConnections.list();

// Blob Storage Integrations - Storage configuration
client.blobStorageIntegrations.list();

// SCIM - Identity management
client.scim.getServiceProviderConfig();

// Ingestion - Legacy batch ingestion (deprecated)
client.ingestion.batch(request);

Request Options

All resource methods accept optional request options for customizing behavior.

interface RequestOptions {
  timeoutInSeconds?: number;
  maxRetries?: number;
  abortSignal?: AbortSignal;
  xLangfuseSdkName?: string | undefined;
  xLangfuseSdkVersion?: string | undefined;
  xLangfusePublicKey?: string | undefined;
  queryParams?: Record<string, unknown>;
  headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
}

Parameters:

  • timeoutInSeconds - Request timeout (default: 60 seconds)
  • maxRetries - Maximum retry attempts (default: 2)
  • abortSignal - AbortSignal for request cancellation
  • xLangfuseSdkName - Override SDK name for this request
  • xLangfuseSdkVersion - Override SDK version for this request
  • xLangfusePublicKey - Override public key for this request
  • queryParams - Additional query parameters
  • headers - Additional headers for this request

Usage Example:

// Custom timeout and retries
const trace = await client.trace.get('trace-id', {
  timeoutInSeconds: 30,
  maxRetries: 5
});

// Request cancellation
const controller = new AbortController();
const promise = client.trace.list({ page: 1 }, {
  abortSignal: controller.signal
});

// Cancel if needed
setTimeout(() => controller.abort(), 5000);

// Custom headers
const prompts = await client.prompts.list({}, {
  headers: {
    'X-Custom-Header': 'value'
  }
});

Core Concepts

Authentication

The client uses HTTP Basic Authentication with your Langfuse API keys:

  • Username: Public API key (starts with pk-lf-)
  • Password: Secret API key (starts with sk-lf-)
const client = new LangfuseAPIClient({
  environment: 'https://cloud.langfuse.com',
  username: 'pk-lf-your-public-key',
  password: 'sk-lf-your-secret-key'
});

Best Practice: Always use environment variables for API keys:

import { getEnv } from '@langfuse/core';

const client = new LangfuseAPIClient({
  environment: getEnv('LANGFUSE_BASE_URL') || 'https://cloud.langfuse.com',
  username: getEnv('LANGFUSE_PUBLIC_KEY'),
  password: getEnv('LANGFUSE_SECRET_KEY')
});

Lazy Loading

Resource clients are created lazily on first access, improving performance and memory usage:

const client = new LangfuseAPIClient(options);

// No resource clients created yet

const trace = await client.trace.get('id');
// Trace client created on first access

const prompt = await client.prompts.get('name');
// Prompts client created on first access

Retry Logic

The client automatically retries failed requests with exponential backoff:

  • Default retries: 2 attempts (3 total tries)
  • Retryable errors: Network errors, 5xx server errors, 429 rate limiting
  • Non-retryable: 4xx client errors (except 429)
// Customize retry behavior
const result = await client.trace.get('trace-id', {
  maxRetries: 5,
  timeoutInSeconds: 30
});

Error Handling

The client throws structured errors for different scenarios:

import {
  LangfuseAPIClient,
  LangfuseAPIError,
  LangfuseAPITimeoutError
} from '@langfuse/core';

try {
  const trace = await client.trace.get('invalid-id');
} catch (error) {
  if (error instanceof LangfuseAPITimeoutError) {
    console.error('Request timed out');
  } else if (error instanceof LangfuseAPIError) {
    console.error('API error:', error.statusCode, error.body);
  } else {
    console.error('Unexpected error:', error);
  }
}

See Error Handling for detailed error documentation.

Pagination

List operations support pagination with consistent parameters:

// Paginated list
const traces = await client.trace.list({
  page: 1,        // Page number (starts at 1)
  limit: 50       // Items per page (default: 50)
});

// Response structure
interface PaginatedResponse<T> {
  data: T[];
  meta: {
    page: number;
    limit: number;
    totalItems: number;
    totalPages: number;
  };
}

// Iterate through pages
async function getAllTraces() {
  const allTraces = [];
  let page = 1;

  while (true) {
    const response = await client.trace.list({ page, limit: 100 });
    allTraces.push(...response.data);

    if (page >= response.meta.totalPages) break;
    page++;
  }

  return allTraces;
}

Filtering and Sorting

Many list operations support filtering and sorting:

// Filter traces
const traces = await client.trace.list({
  userId: 'user-123',
  sessionId: 'session-456',
  fromTimestamp: '2024-01-01T00:00:00Z',
  toTimestamp: '2024-12-31T23:59:59Z',
  tags: ['production', 'api'],
  name: 'chat-completion',
  orderBy: 'timestamp.desc'
});

// Filter prompts
const prompts = await client.prompts.list({
  name: 'chat-prompt',
  tag: 'production',
  label: 'latest',
  fromUpdatedAt: '2024-01-01T00:00:00Z'
});

Field Selection

Optimize response payload by selecting specific field groups:

// Get trace with specific fields
const trace = await client.trace.list({
  fields: 'core,scores,metrics'  // Exclude large fields like observations
});

// Available field groups:
// - core: Always included (id, name, timestamp, etc.)
// - io: Input/output data
// - scores: Associated scores
// - observations: Nested observations
// - metrics: Aggregated metrics

Supplier Pattern

Configuration values can be static or dynamic using the Supplier pattern:

type Supplier<T> = T | (() => T);

// Static value
const client1 = new LangfuseAPIClient({
  environment: 'https://cloud.langfuse.com',
  username: 'pk-lf-...'
});

// Dynamic value (evaluated on each request)
const client2 = new LangfuseAPIClient({
  environment: () => getCurrentEnvironmentUrl(),
  username: () => getRotatingApiKey(),
  headers: {
    'X-Request-Id': () => generateRequestId()
  }
});

Usage Patterns

Basic Client Setup

import { LangfuseAPIClient } from '@langfuse/core';

const client = new LangfuseAPIClient({
  environment: 'https://cloud.langfuse.com',
  username: process.env.LANGFUSE_PUBLIC_KEY,
  password: process.env.LANGFUSE_SECRET_KEY
});

// Use the client
const trace = await client.trace.get('trace-id');

Multi-Environment Setup

import { LangfuseAPIClient } from '@langfuse/core';

class LangfuseService {
  private clients: Map<string, LangfuseAPIClient>;

  constructor() {
    this.clients = new Map([
      ['production', new LangfuseAPIClient({
        environment: 'https://cloud.langfuse.com',
        username: process.env.PROD_PUBLIC_KEY,
        password: process.env.PROD_SECRET_KEY
      })],
      ['staging', new LangfuseAPIClient({
        environment: 'https://staging.langfuse.com',
        username: process.env.STAGING_PUBLIC_KEY,
        password: process.env.STAGING_SECRET_KEY
      })]
    ]);
  }

  getClient(env: string): LangfuseAPIClient {
    return this.clients.get(env) || this.clients.get('production')!;
  }
}

Request Cancellation

import { LangfuseAPIClient } from '@langfuse/core';

async function fetchWithTimeout(
  client: LangfuseAPIClient,
  traceId: string,
  timeoutMs: number
) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), timeoutMs);

  try {
    return await client.trace.get(traceId, {
      abortSignal: controller.signal
    });
  } finally {
    clearTimeout(timeout);
  }
}

// Use it
const trace = await fetchWithTimeout(client, 'trace-id', 5000);

Error Recovery

import {
  LangfuseAPIClient,
  LangfuseAPIError,
  LangfuseAPITimeoutError
} from '@langfuse/core';

async function fetchTraceWithRecovery(
  client: LangfuseAPIClient,
  traceId: string
) {
  try {
    return await client.trace.get(traceId, {
      maxRetries: 3,
      timeoutInSeconds: 30
    });
  } catch (error) {
    if (error instanceof LangfuseAPITimeoutError) {
      console.warn('Request timed out, using fallback');
      return null;
    }

    if (error instanceof LangfuseAPIError) {
      if (error.statusCode === 404) {
        console.warn('Trace not found');
        return null;
      }

      if (error.statusCode === 429) {
        console.warn('Rate limited, waiting before retry');
        await new Promise(resolve => setTimeout(resolve, 5000));
        return fetchTraceWithRecovery(client, traceId);
      }
    }

    throw error;
  }
}

Type Definitions

class LangfuseAPIClient {
  constructor(options: LangfuseAPIClient.Options);
  readonly annotationQueues: AnnotationQueues;
  readonly blobStorageIntegrations: BlobStorageIntegrations;
  readonly comments: Comments;
  readonly datasetItems: DatasetItems;
  readonly datasetRunItems: DatasetRunItems;
  readonly datasets: Datasets;
  readonly health: Health;
  readonly ingestion: Ingestion;
  readonly llmConnections: LlmConnections;
  readonly media: Media;
  readonly metrics: Metrics;
  readonly models: Models;
  readonly observations: Observations;
  readonly organizations: Organizations;
  readonly projects: Projects;
  readonly promptVersion: PromptVersion;
  readonly prompts: Prompts;
  readonly scim: Scim;
  readonly scoreConfigs: ScoreConfigs;
  readonly scoreV2: ScoreV2;
  readonly score: Score;
  readonly sessions: Sessions;
  readonly trace: Trace;
}

namespace LangfuseAPIClient {
  interface Options {
    environment: core.Supplier<string>;
    baseUrl?: core.Supplier<string>;
    username?: core.Supplier<string | undefined>;
    password?: core.Supplier<string | undefined>;
    xLangfuseSdkName?: core.Supplier<string | undefined>;
    xLangfuseSdkVersion?: core.Supplier<string | undefined>;
    xLangfusePublicKey?: core.Supplier<string | undefined>;
    headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
  }
}

interface RequestOptions {
  timeoutInSeconds?: number;
  maxRetries?: number;
  abortSignal?: AbortSignal;
  xLangfuseSdkName?: string | undefined;
  xLangfuseSdkVersion?: string | undefined;
  xLangfusePublicKey?: string | undefined;
  queryParams?: Record<string, unknown>;
  headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
}

type Supplier<T> = T | (() => T);

Best Practices

  1. Environment Variables: Always use environment variables for API keys, never hardcode them
  2. Singleton Client: Create one client instance per environment and reuse it throughout your application
  3. Error Handling: Always wrap API calls in try-catch blocks and handle specific error types
  4. Pagination: Implement proper pagination for list operations to avoid memory issues
  5. Field Selection: Use field selection to minimize response payload when full data isn't needed
  6. Timeout Configuration: Set appropriate timeouts based on your use case (longer for batch operations)
  7. Retry Strategy: Customize retry logic for critical operations vs. non-critical queries
  8. Request Cancellation: Implement cancellation for user-triggered operations that may be abandoned
  9. Logging: Use the SDK logger to track API interactions for debugging
  10. Type Safety: Leverage TypeScript types for compile-time validation of requests

Install with Tessl CLI

npx tessl i tessl/npm-langfuse--core

docs

api-client.md

api-resources.md

constants.md

errors.md

index.md

logger.md

media.md

utils.md

tile.json