Implementation:Langfuse Langfuse API Commons Schema

Knowledge Sources	Langfuse
Domains	API, Schema Definition, Data Model
Last Updated	2026-02-14 00:00 GMT

Overview

Defines the shared type definitions, enumerations, and error types used across the Langfuse server API, written in Fern API definition language (YAML).

Description

This file is the commons schema for the Langfuse public API, authored using the Fern API definition framework. It contains all the core data types that are shared across multiple API endpoints. The file defines the canonical shapes of Langfuse's primary domain objects including Traces, Observations, Scores, Sessions, Datasets, Models, and their related sub-types.

Key type families defined in this schema include:

• Trace types -- Trace, TraceWithDetails, TraceWithFullDetails representing traces at various levels of detail. Traces are the top-level unit of observability data.
• Observation types -- Observation and ObservationsView for individual LLM calls or spans within a trace. Includes usage metrics, cost details, model parameters, and prompt references.
• Score types -- Two versioned score systems: V1 (ScoreV1) and V2 (Score). Both are discriminated unions over NUMERIC, CATEGORICAL, BOOLEAN data types, with V2 also supporting CORRECTION. Scores can target traces, observations, sessions, or dataset runs.
• Session types -- Session and SessionWithTraces for grouping traces into conversation sessions.
• Dataset types -- Dataset, DatasetItem, DatasetRun, DatasetRunItem, DatasetRunWithItems for managing evaluation datasets and experiment runs.
• Model types -- Model, PricingTier, PricingTierCondition, PricingTierInput, and ModelPrice for defining LLM model pricing, including support for tiered/conditional pricing based on usage patterns.
• Comment type -- Comment for annotation comments on traces, observations, sessions, and prompts.
• Score configuration -- ScoreConfig and ConfigCategory for defining valid score ranges and categories.
• Enumerations -- ObservationLevel, ModelUsageUnit, CommentObjectType, DatasetStatus, ScoreSource, ScoreConfigDataType, ScoreDataType, PricingTierOperator.
• Error types -- Standard HTTP error responses (400, 401, 403, 404, 405).

This file serves as the single source of truth for the public API contract and is used by the Fern CLI to generate the OpenAPI specification.

Usage

Use this file when:

• Adding or modifying a shared data type that appears in multiple Langfuse API endpoints.
• Defining new enumerations or error types for the public API.
• Understanding the canonical shape of core Langfuse domain objects (traces, observations, scores, datasets, models).
• Regenerating the OpenAPI specification via the Fern CLI after making API changes.

Code Reference

Source Location

• Repository: Langfuse
• File: fern/apis/server/definition/commons.yml
• Lines: 1-829

Signature

types:
  Trace:
    properties:
      id: string
      timestamp: datetime
      name: nullable<string>
      input: optional<unknown>
      output: optional<unknown>
      sessionId: nullable<string>
      ...

  TraceWithDetails:
    extends: Trace
    properties:
      htmlPath: string
      latency: optional<nullable<double>>
      totalCost: optional<nullable<double>>
      ...

  Observation:
    properties:
      id: string
      traceId: nullable<string>
      type: string
      name: nullable<string>
      ...

  ScoreV1:
    discriminant: "dataType"
    union:
      NUMERIC: NumericScoreV1
      CATEGORICAL: CategoricalScoreV1
      BOOLEAN: BooleanScoreV1

  Score:
    discriminant: "dataType"
    union:
      NUMERIC: NumericScore
      CATEGORICAL: CategoricalScore
      BOOLEAN: BooleanScore
      CORRECTION: CorrectionScore

  Model:
    properties:
      id: string
      modelName: string
      matchPattern: string
      pricingTiers: list<PricingTier>
      ...

errors:
  Error:
    status-code: 400
  UnauthorizedError:
    status-code: 401
  AccessDeniedError:
    status-code: 403
  NotFoundError:
    status-code: 404
  MethodNotAllowedError:
    status-code: 405

Import

# Referenced from other Fern definition files:
imports:
  commons: ./commons.yml

I/O Contract

Inputs

Name	Type	Required	Description
N/A	N/A	N/A	This is a type definition file; it does not accept runtime inputs. Types defined here are consumed by API endpoint definitions.

Outputs

Name	Type	Description
types	YAML type definitions	Shared data types (Trace, Observation, Score, Session, Dataset, Model, Comment, ScoreConfig, enums)
errors	YAML error definitions	HTTP error response types (400, 401, 403, 404, 405)

Usage Examples

# Referencing commons types from another Fern endpoint definition:
imports:
  commons: ./commons.yml

service:
  endpoints:
    getTrace:
      method: GET
      path: /traces/{traceId}
      response: commons.TraceWithFullDetails

    createScore:
      method: POST
      path: /scores
      request:
        body:
          properties:
            name: string
            value: commons.CreateScoreValue
            traceId: string
            dataType: optional<commons.ScoreDataType>