Implementation:Langfuse Langfuse API Dataset 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 items API, providing CRUD operations for individual items within Langfuse datasets including versioned retrieval and source trace linking.

Description

This file defines the public API contract for managing dataset items under /api/public. Dataset items represent individual test cases within a dataset, containing input data, expected output, and metadata. The file contains four endpoints:

• POST /api/public/dataset-items -- Create a dataset item (upserts on id)
• GET /api/public/dataset-items/{id} -- Get a single dataset item by ID
• GET /api/public/dataset-items -- List dataset items with optional filtering by dataset name, source trace/observation, and point-in-time versioning
• DELETE /api/public/dataset-items/{id} -- Delete a dataset item and all its associated run items (irreversible)

The list endpoint supports a version parameter (ISO 8601 timestamp) that returns the state of the dataset at a given point in time.

Usage

Developers reference this definition when:

• Building dataset management workflows for evaluation pipelines
• Generating SDK types for dataset item operations
• Implementing versioned dataset retrieval for reproducible experiments
• Understanding the relationship between dataset items and source traces

Code Reference

Source Location

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

Signature

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

    get:
      docs: Get a dataset item
      method: GET
      path: /dataset-items/{id}
      response: commons.DatasetItem

    list:
      docs: Get dataset items. Optionally specify a version to get the items
            as they existed at that point in time.
      method: GET
      path: /dataset-items
      request:
        name: GetDatasetItemsRequest
        query-parameters:
          datasetName: optional<string>
          sourceTraceId: optional<string>
          sourceObservationId: optional<string>
          version: optional<datetime>
          page: optional<integer>
          limit: optional<integer>
      response: PaginatedDatasetItems

    delete:
      docs: Delete a dataset item and all its run items
      method: DELETE
      path: /dataset-items/{id}
      response: DeleteDatasetItemResponse

I/O Contract

Endpoints

Method	Path	Description
POST	/api/public/dataset-items	Create or upsert a dataset item by id
GET	/api/public/dataset-items/{id}	Get a specific dataset item
GET	/api/public/dataset-items	List items with optional filters (datasetName, sourceTraceId, sourceObservationId, version)
DELETE	/api/public/dataset-items/{id}	Permanently delete a dataset item and its run items

Key Types

Type Name	Description
CreateDatasetItemRequest	Request with datasetName, input, expectedOutput, metadata, source trace/observation IDs, optional id and status
PaginatedDatasetItems	Paginated list of commons.DatasetItem with MetaResponse
DeleteDatasetItemResponse	Confirmation message after deletion

Usage Examples

# Create a dataset item
curl -X POST "https://cloud.langfuse.com/api/public/dataset-items" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetName": "qa-evaluation",
    "input": {"question": "What is Langfuse?"},
    "expectedOutput": {"answer": "An open-source LLM engineering platform"},
    "metadata": {"category": "product"}
  }'

# List dataset items with versioning
curl -X GET "https://cloud.langfuse.com/api/public/dataset-items?datasetName=qa-evaluation&version=2026-01-21T14:35:42Z&page=1&limit=50" \
  -H "Authorization: Bearer $API_KEY"

# Delete a dataset item
curl -X DELETE "https://cloud.langfuse.com/api/public/dataset-items/item-123" \
  -H "Authorization: Bearer $API_KEY"

Related Pages

• Environment:Langfuse_Langfuse_Node_24_Runtime