Implementation:Langfuse Langfuse API Dataset Run Items Schema

Knowledge Sources	Langfuse Langfuse API Reference
Domains	API, Datasets
Last Updated	2026-02-14 00:00 GMT

Overview

Fern API definition for the dataset run items API, used to link individual dataset items to their evaluation trace results within experiment runs.

Description

This file defines the public API contract for managing dataset run items under /api/public. Dataset run items represent the junction between a dataset item and the trace/observation produced during an experiment run. The file contains two endpoints:

• POST /api/public/dataset-run-items -- Create a dataset run item, linking a dataset item to a trace (and optionally an observation) within a named run
• GET /api/public/dataset-run-items -- List dataset run items filtered by dataset ID and run name (paginated)

The create endpoint also supports run-level metadata and descriptions, which are updated if the run already exists. An optional datasetVersion timestamp allows pinning experiments to a specific point-in-time snapshot of the dataset.

Usage

Developers reference this definition when:

• Building evaluation pipelines that execute dataset items and record results
• Generating SDK types for experiment run management
• Understanding how dataset items map to their evaluation traces
• Implementing versioned experiment runs

Code Reference

Source Location

• Repository: Langfuse
• File: fern/apis/server/definition/dataset-run-items.yml
• Lines: 1-57

Signature

service:
  auth: true
  base-path: /api/public
  endpoints:
    create:
      method: POST
      docs: Create a dataset run item
      path: /dataset-run-items
      request: CreateDatasetRunItemRequest
      response: commons.DatasetRunItem

    list:
      method: GET
      docs: List dataset run items
      path: /dataset-run-items
      request:
        name: ListDatasetRunItemsRequest
        query-parameters:
          datasetId: string
          runName: string
          page: optional<integer>
          limit: optional<integer>
      response: PaginatedDatasetRunItems

types:
  CreateDatasetRunItemRequest:
    properties:
      runName: string
      runDescription: optional<string>
      metadata: optional<unknown>
      datasetItemId: string
      observationId: optional<string>
      traceId: optional<string>
      datasetVersion: optional<datetime>

  PaginatedDatasetRunItems:
    properties:
      data: list<commons.DatasetRunItem>
      meta: pagination.MetaResponse

I/O Contract

Endpoints

Method	Path	Description
POST	/api/public/dataset-run-items	Create a run item linking a dataset item to a trace/observation within a named run
GET	/api/public/dataset-run-items	List run items filtered by datasetId and runName (both required)

Key Types

Type Name	Description
CreateDatasetRunItemRequest	Request with runName, datasetItemId, traceId, optional observationId, runDescription, metadata, and datasetVersion
PaginatedDatasetRunItems	Paginated list of commons.DatasetRunItem with MetaResponse

Usage Examples

# Create a dataset run item
curl -X POST "https://cloud.langfuse.com/api/public/dataset-run-items" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "runName": "experiment-v2",
    "runDescription": "Testing with improved prompt",
    "datasetItemId": "item-123",
    "traceId": "trace-456",
    "observationId": "obs-789"
  }'

# List run items for a specific dataset and run
curl -X GET "https://cloud.langfuse.com/api/public/dataset-run-items?datasetId=dataset-123&runName=experiment-v2&page=1&limit=50" \
  -H "Authorization: Bearer $API_KEY"

Related Pages

• Environment:Langfuse_Langfuse_Node_24_Runtime