Implementation:Langfuse Langfuse API Datasets Schema

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

Overview

Fern API definition for the datasets v2 API, providing CRUD operations for datasets and their experiment runs, including JSON Schema validation support for dataset items.

Description

This file defines the public API contract for managing datasets and dataset runs under /api/public. Datasets are containers for evaluation test cases, while runs represent experiment executions against those datasets. The file contains six endpoints:

Dataset Management:

• GET /api/public/v2/datasets -- List all datasets (paginated)
• GET /api/public/v2/datasets/{datasetName} -- Get a dataset by name
• POST /api/public/v2/datasets -- Create a new dataset with optional JSON Schema validation for inputs and expected outputs

Run Management:

• GET /api/public/datasets/{datasetName}/runs/{runName} -- Get a specific run with its items
• DELETE /api/public/datasets/{datasetName}/runs/{runName} -- Delete a run and all its run items (irreversible)
• GET /api/public/datasets/{datasetName}/runs -- List all runs for a dataset (paginated)

The dataset endpoints use the /v2/ prefix while run endpoints use the original path structure.

Usage

Developers reference this definition when:

• Building evaluation frameworks that create and manage datasets
• Generating SDK types for dataset and run operations
• Implementing JSON Schema validation for dataset inputs/outputs
• Managing experiment runs programmatically

Code Reference

Source Location

• Repository: Langfuse
• File: fern/apis/server/definition/datasets.yml
• Lines: 1-91

Signature

service:
  auth: true
  base-path: /api/public
  endpoints:
    list:
      method: GET
      docs: Get all datasets
      path: /v2/datasets
      response: PaginatedDatasets

    get:
      method: GET
      docs: Get a dataset
      path: /v2/datasets/{datasetName}
      response: commons.Dataset

    create:
      method: POST
      docs: Create a dataset
      path: /v2/datasets
      request: CreateDatasetRequest
      response: commons.Dataset

    getRun:
      method: GET
      docs: Get a dataset run and its items
      path: /datasets/{datasetName}/runs/{runName}
      response: commons.DatasetRunWithItems

    deleteRun:
      method: DELETE
      docs: Delete a dataset run and all its run items
      path: /datasets/{datasetName}/runs/{runName}
      response: DeleteDatasetRunResponse

    getRuns:
      method: GET
      docs: Get dataset runs
      path: /datasets/{datasetName}/runs
      response: PaginatedDatasetRuns

types:
  CreateDatasetRequest:
    properties:
      name: string
      description: optional<string>
      metadata: optional<unknown>
      inputSchema: optional<unknown>
      expectedOutputSchema: optional<unknown>

I/O Contract

Endpoints

Method	Path	Description
GET	/api/public/v2/datasets	List all datasets (paginated)
GET	/api/public/v2/datasets/{datasetName}	Get a dataset by name
POST	/api/public/v2/datasets	Create a dataset with optional JSON Schema validation
GET	/api/public/datasets/{datasetName}/runs/{runName}	Get a run with all its items
DELETE	/api/public/datasets/{datasetName}/runs/{runName}	Permanently delete a run and its items
GET	/api/public/datasets/{datasetName}/runs	List runs for a dataset (paginated)

Key Types

Type Name	Description
PaginatedDatasets	Paginated list of commons.Dataset with MetaResponse
CreateDatasetRequest	Request with name, description, metadata, inputSchema, and expectedOutputSchema
PaginatedDatasetRuns	Paginated list of commons.DatasetRun with MetaResponse
DeleteDatasetRunResponse	Confirmation message after run deletion

Usage Examples

# Create a dataset with JSON Schema validation
curl -X POST "https://cloud.langfuse.com/api/public/v2/datasets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "qa-evaluation",
    "description": "Q&A evaluation dataset",
    "inputSchema": {"type": "object", "properties": {"question": {"type": "string"}}, "required": ["question"]},
    "expectedOutputSchema": {"type": "object", "properties": {"answer": {"type": "string"}}, "required": ["answer"]}
  }'

# List all datasets
curl -X GET "https://cloud.langfuse.com/api/public/v2/datasets?page=1&limit=20" \
  -H "Authorization: Bearer $API_KEY"

# Get a specific run with its items
curl -X GET "https://cloud.langfuse.com/api/public/datasets/qa-evaluation/runs/experiment-v2" \
  -H "Authorization: Bearer $API_KEY"

Related Pages

• Environment:Langfuse_Langfuse_Node_24_Runtime