Langfuse JS/TS SDKs
    Preparing search index...

    Class LangfuseClient

    Main client for interacting with the Langfuse API.

    The LangfuseClient provides access to all non-tracing Langfuse functionality:

    • Prompt management (langfuse.prompt) — fetch, cache, compile, and version prompts
    • Datasets (langfuse.dataset) — manage test datasets and link items to runs
    • Experiments (langfuse.experiment) — run tasks + evaluators over datasets
    • Scores (langfuse.score) — create evaluation/feedback scores for traces and observations
    • Media (langfuse.media) — upload media and resolve media references
    • Direct API access (langfuse.api) — the full generated Langfuse REST API client

    Tracing/observability is intentionally NOT part of this client. To trace your application, use @langfuse/tracing (instrumentation) together with the LangfuseSpanProcessor from @langfuse/otel (export).

    // Initialize with explicit credentials
    const langfuse = new LangfuseClient({
      publicKey: "pk-lf-...",
      secretKey: "sk-lf-...",
      baseUrl: "https://cloud.langfuse.com"
    });

    // Or use environment variables
    const langfuse = new LangfuseClient();

    // Use the client
    const prompt = await langfuse.prompt.get("my-prompt");
    const compiledPrompt = prompt.compile({ variable: "value" });
    Index

    Constructors

    constructor

    Properties

    api dataset experiment media prompt score

    Methods

    flush getExperimentUrl getProjectId getTraceUrl shutdown

    Constructors

    • Creates a new LangfuseClient instance.

      Parameters

      • Optionalparams: LangfuseClientParams

        Configuration parameters. If not provided, will use environment variables.

      Returns LangfuseClient

      Will log warnings if required credentials are not provided

      // With explicit configuration
      const client = new LangfuseClient({
        publicKey: "pk_...",
        secretKey: "sk_...",
        baseUrl: "https://your-instance.langfuse.com"
      });

      // Using environment variables
      const client = new LangfuseClient();

    Properties

    api: LangfuseAPIClient

    Direct access to the underlying Langfuse API client. Use this for advanced API operations not covered by the high-level managers.

    dataset: DatasetManager

    Manager for dataset operations including retrieval and item linking.

    experiment: ExperimentManager

    Manager for running experiments on datasets and data items.

    The experiment manager provides comprehensive functionality for:

    • Running tasks on datasets or custom data arrays
    • Evaluating outputs with custom or pre-built evaluators
    • Tracking experiment runs with automatic tracing
    • Generating formatted result summaries
    • Integrating with AutoEvals library evaluators
    const langfuse = new LangfuseClient();

    const result = await langfuse.experiment.run({
      name: "Model Evaluation",
      description: "Testing model performance on Q&A tasks",
      data: [
        { input: "What is 2+2?", expectedOutput: "4" },
        { input: "What is the capital of France?", expectedOutput: "Paris" }
      ],
      task: async ({ input }) => {
        // Your model/task implementation
        const response = await myModel.generate(input);
        return response;
      },
      evaluators: [
        async ({ output, expectedOutput }) => ({
          name: "exact_match",
          value: output.trim().toLowerCase() === expectedOutput.toLowerCase() ? 1 : 0
        })
      ]
    });

    console.log(await result.format());

    const dataset = await langfuse.dataset.get("my-test-dataset");
    const result = await dataset.runExperiment({
      name: "Production Readiness Test",
      task: myTask,
      evaluators: [accuracyEvaluator, latencyEvaluator],
      runEvaluators: [overallQualityEvaluator]
    });

    4.0.0

    media: MediaManager

    Manager for media upload and reference resolution.

    prompt: PromptManager

    Manager for prompt operations including creation, retrieval, and caching.

    score: ScoreManager

    Manager for score creation and batch processing.

    Methods

    • Flushes any pending score events to the Langfuse API.

      This method ensures all queued scores are sent immediately rather than waiting for the automatic flush interval or batch size threshold.

      Returns Promise<void>

      Promise that resolves when all pending scores have been sent

      langfuse.score.create({ name: "quality", value: 0.8 });
      await langfuse.flush(); // Ensures the score is sent immediately

    • Generates a URL to view an experiment in the Langfuse UI.

      Parameters

      • experimentId: string

        The ID of the experiment, e.g. ExperimentResult.experimentId

      Returns Promise<string>

      Promise that resolves to the experiment results URL

    • Internal

      Returns the ID of the project the API keys belong to. Cached after the first successful lookup.

      Returns Promise<string>

    • Generates a URL to view a specific trace in the Langfuse UI.

      Parameters

      • traceId: string

        The ID of the trace to generate a URL for

      Returns Promise<string>

      Promise that resolves to the trace URL

      const traceId = "trace-123";
      const url = await langfuse.getTraceUrl(traceId);
      console.log(`View trace at: ${url}`);

    • Gracefully shuts down the client by flushing all pending data.

      This method should be called before your application exits to ensure all data is sent to Langfuse.

      Returns Promise<void>

      Promise that resolves when shutdown is complete

      // Before application exit
      await langfuse.shutdown();

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods