---
title: "Preview Dataset From Hub"
method: POST
path: "/v1/datasets/preview-from-hub"
tags: ["datasets"]
---

# Preview Dataset From Hub

`POST /v1/datasets/preview-from-hub`

## Request

- Base URL: `https://api.pioneer.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pioneer.ai/v1/datasets/preview-from-hub`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/pioneer/apis/brain-api/docs/v1/datasets/preview-from-hub/post.ts> (a function with typed inputs; its response is checked against the schema)

Preview a dataset from HuggingFace Hub without saving it.

Fetches the dataset and returns a preview (first 50 rows, schema, metadata)
for user review before confirming the import.

User-authenticated requests require hf_token. Sandbox run keys omit it and
import public repos anonymously. Gated or private repos must be imported
in the Fastino UI with a user token.

## Request body

- HuggingFacePullRequest: Request to pull dataset from HuggingFace Hub.
  - `repo_id` string, required: HuggingFace repo ID to pull from
  - `config_name` string, nullable: HuggingFace dataset configuration, distinct from the local Fastino name
  - `revision` string, nullable: Specific revision/branch to pull
  - `name` string, nullable: Name for the local dataset (defaults to repo name)
  - `hf_token` string, nullable: HuggingFace API token. Required for user-authenticated imports. Sandbox run keys must omit this field and can only import public repos. Gated or private repos must be imported in the Fastino UI.
  - `session_id` string, nullable: Session ID for SSE log streaming
  - `column_mapping` object, nullable: Column mapping from source to standard names
  - `dataset_type` string, nullable: Dataset type (ner, classification, custom)
  - `type` 'training' | 'evaluation' | 'benchmark', nullable: Dataset purpose: 'training' (trainable), 'evaluation' (not trainable), 'benchmark' (system-managed, evaluation-only; cannot be created via this endpoint). This model is also bound to POST /felix/datasets/preview-from-hub, which ignores this field entirely -- nothing is persisted on a preview.

## Response `200`

Successful Response

- HuggingFacePullPreviewResponse: Response containing preview data from a HuggingFace dataset pull (without saving).
  - `preview_rows` object[], required: Sample rows from the dataset (first 50 rows)
  - `total_rows` integer, required: Total number of rows in the dataset
  - `columns` string[], required: List of column names
  - `dataset_type` string, required: Inferred dataset type (classification, ner, custom)
  - `schema_` object, nullable: Inferred schema mapping column names to data types
  - `metadata` object, nullable: Dataset metadata from HuggingFace

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-24** `0e5e86e2bae5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pioneer/apis/brain-api/changes/v1/datasets/preview-from-hub/post.md)

---

[API](https://skmtc.dev/pioneer/apis/brain-api.md) - [All operations](https://skmtc.dev/pioneer/apis/brain-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pioneer/apis/brain-api/revisions/0e5e86e2bae5?raw)