Implementation:Langfuse Langfuse API Ingestion Schema

Knowledge Sources	Langfuse
Domains	API, Data Ingestion, Observability
Last Updated	2026-02-14 00:00 GMT

Overview

Defines the Fern API schema for the Langfuse batch ingestion endpoint, including all event types, request/response shapes, and observation body definitions.

Description

This file specifies the legacy batch ingestion API endpoint (POST /api/public/ingestion) using the Fern API definition language. The endpoint is marked as deprecated in favor of the OpenTelemetry endpoint (/api/public/otel/v1/traces), but remains a core part of the Langfuse data pipeline.

The ingestion API accepts batches of events via a single HTTP request, where each event represents a create or update operation on a trace, observation (span/generation/event), or score. The endpoint uses a 207 Multi-Status response pattern, returning per-event success/error information.

Key type definitions include:

• IngestionEvent -- A discriminated union on the type field supporting: trace-create, score-create, span-create, span-update, generation-create, generation-update, event-create, sdk-log, and deprecated observation-create/observation-update.
• Body types -- TraceBody, ScoreBody, CreateSpanBody, UpdateSpanBody, CreateGenerationBody, UpdateGenerationBody, CreateEventBody, UpdateEventBody, SDKLogBody, and legacy ObservationBody.
• ObservationType -- Enum of span types: SPAN, GENERATION, EVENT, AGENT, TOOL, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING, GUARDRAIL.
• Usage types -- IngestionUsage (union of standard and OpenAI formats), OpenAIUsage, UsageDetails (union of generic map, OpenAICompletionUsageSchema, OpenAIResponseUsageSchema).
• Event envelope -- BaseEvent with id, timestamp, and optional metadata. All event types extend this.
• Response types -- IngestionResponse containing lists of IngestionSuccess and IngestionError objects.

The body types use an inheritance chain: OptionalObservationBody -> CreateEventBody -> CreateSpanBody -> CreateGenerationBody, each adding additional optional fields.

⚠️ Deprecation Note: This file contains legacy schema types including LegacySpanPostSchema, LegacySpanPatchSchema, LegacyGenerationsCreateSchema, LegacyGenerationPatchSchema, LegacyObservationBody, legacyObservationCreateEvent, and legacyObservationUpdateEvent, all maintained only for backwards compatibility with older SDK versions. The EnvironmentName export is deprecated in favor of PublicEnvironmentName or InternalEnvironmentName. The ingestionEvent export is deprecated in favor of createIngestionEventSchema(). Consumers should migrate to the recommended alternatives.

Usage

Use this file when:

• Understanding or modifying the batch ingestion API contract.
• Adding new event types or fields to the ingestion pipeline.
• Debugging SDK-to-server communication for trace/observation/score creation.
• Regenerating the OpenAPI specification after ingestion API changes.

Code Reference

Source Location

• Repository: Langfuse
• File: fern/apis/server/definition/ingestion.yml
• Lines: 1-447

Signature

service:
  auth: true
  base-path: /api/public
  endpoints:
    batch:
      availability:
        status: deprecated
      method: POST
      path: /ingestion
      request:
        name: IngestionRequest
        body:
          properties:
            batch: list<IngestionEvent>
            metadata: optional<unknown>
      response:
        type: IngestionResponse
        status-code: 207

types:
  IngestionEvent:
    discriminant: "type"
    union:
      trace-create: TraceEvent
      score-create: ScoreEvent
      span-create: CreateSpanEvent
      span-update: UpdateSpanEvent
      generation-create: CreateGenerationEvent
      generation-update: UpdateGenerationEvent
      event-create: CreateEventEvent
      sdk-log: SDKLogEvent
      observation-create: CreateObservationEvent
      observation-update: UpdateObservationEvent

  IngestionResponse:
    properties:
      successes: list<IngestionSuccess>
      errors: list<IngestionError>

Import

imports:
  pagination: ./utils/pagination.yml
  commons: ./commons.yml

I/O Contract

Inputs

Name	Type	Required	Description
batch	list<IngestionEvent>	Yes	Array of tracing events to be ingested, discriminated by the type attribute
metadata	optional<unknown>	No	Optional metadata field used by SDKs for debugging

Outputs

Name	Type	Description
successes	list<IngestionSuccess>	Array of successfully processed events with id and HTTP status code
errors	list<IngestionError>	Array of failed events with id, status code, message, and error details

Usage Examples

# Example: Trace Create Request
- request:
    batch:
      - id: abcdef-1234-5678-90ab
        timestamp: "2022-01-01T00:00:00.000Z"
        type: "trace-create"
        body:
          id: abcdef-1234-5678-90ab
          timestamp: "2022-01-01T00:00:00.000Z"
          environment: "production"
          name: "My Trace"
          userId: "1234-5678-90ab-cdef"
          input: "My input"
          output: "My output"
          sessionId: "1234-5678-90ab-cdef"
          tags: ["tag1", "tag2"]
          public: true
  response:
    body:
      successes:
        - id: abcdef-1234-5678-90ab
          status: 201
      errors: []

# Example: Generation Create with usage details
- request:
    batch:
      - id: gen-event-001
        timestamp: "2024-01-15T10:00:00.000Z"
        type: "generation-create"
        body:
          id: gen-001
          traceId: trace-001
          name: "chat-completion"
          model: "gpt-4o"
          input: "What is Langfuse?"
          output: "Langfuse is an open-source LLM engineering platform."
          usageDetails:
            prompt_tokens: 15
            completion_tokens: 20
            total_tokens: 35