---
title: "Using the Dataset Viewer API"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source: https://iinventedlight.com/library/notes/hf-dataset-viewer-api.md
source_license: "Apache-2.0 (huggingface/dataset-viewer docs); restated in our own words"
attribution: "Summary by iinventedlight (AI-assisted). Sources: Hugging Face, Quickstart, Apache-2.0 (huggingface/dataset-viewer docs); Hugging Face, Download slices of rows, Apache-2.0 (huggingface/dataset-viewer docs)."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-03
status: published
checked_on: 2026-11-03
as_of: 2026-11-03
confidence: medium
untested: "No HTTP requests were sent to the dataset viewer; response shapes below are taken from the fetched quickstart and rows pages, not from a live call."
category: huggingface-datasets
topic_area: "Dataset Viewer API"
tags: huggingface, dataset-viewer, rest-api, parquet, rows
sources:
  - id: S1
    title: "Quickstart"
    publisher: Hugging Face
    url: https://huggingface.co/docs/dataset-viewer/quick_start
    accessed: 2026-11-03
    license: "Apache-2.0 (huggingface/dataset-viewer docs)"
  - id: S2
    title: "Download slices of rows"
    publisher: Hugging Face
    url: https://huggingface.co/docs/dataset-viewer/rows
    accessed: 2026-11-03
    license: "Apache-2.0 (huggingface/dataset-viewer docs)"
---
# Using the Dataset Viewer API

## Summary
The dataset viewer is a REST API at `https://datasets-server.huggingface.co`. It checks a Hub dataset, lists splits, pages through rows, searches and filters text, and returns Parquet URLs, size, statistics, and Croissant metadata. Nothing has to be installed.

## Calls
Every example is an HTTP GET. A public dataset needs only its name. An account is optional, but gated datasets (the page names CommonVoice and ImageNet) need the user token from your settings, sent as a Bearer token. Private datasets need the same header. They are supported when a PRO user or an Enterprise Hub organization owns them. Without a token, a private or gated name returns an error that the dataset does not exist or is not accessible without authentication.

`dataset` is the dataset name on each of these GET routes:

- `/is-valid` reports whether preview, the row viewer, search, filter, and statistics are available.
- `/splits` lists configs and splits, plus `pending` and `failed`.
- `/first-rows` also needs `config` and `split`, and returns the first 100 rows and the column types.
- `/rows` adds `offset` and `length`. Length is at most 100.
- `/search` adds `query`. It searches string columns, including strings nested in a dictionary, and pages the same way as `/rows`.
- `/filter` adds `where` and `orderby`, again with `offset` and `length` capped at 100.
- `/parquet` lists converted Parquet files.
- `/size` returns row counts and byte sizes for the dataset and for each config and split.
- `/statistics` needs `config` and `split`.
- `/croissant` returns Croissant metadata.

The viewer converts every Hub dataset to Parquet.

## Row slices
`/rows` reads a window of a split without downloading the dataset, but only when Parquet exports already exist. Parameters are `dataset`, `config`, `split`, `offset`, and `length` (maximum 100). The JSON lists column features and rows. `partial: true` means the dataset was too big to slice in full.

Image and audio cells are URLs. An image has `src` (a signed URL that expires), `height`, and `width`. If a cached file is gone, call `/rows` again. Cell text is not truncated, and `truncated_cells` stays empty.

## Claims
- id: C1
  claim: The dataset viewer API needs no installation.
  source: S1
  evidence: "There is no installation or setup required to use the dataset viewer API."
- id: C2
  claim: Private datasets work when a PRO user or an Enterprise Hub organization owns them.
  source: S1
  evidence: "private datasets owned by a PRO user or an Enterprise Hub organization"
- id: C3
  claim: One call downloads at most 100 rows.
  source: S1
  evidence: "You can download slices of 100 rows maximum at a time."
- id: C4
  claim: The viewer converts every Hub dataset to Parquet.
  source: S1
  evidence: "The dataset viewer converts every dataset on the Hub to the Parquet format."
- id: C5
  claim: Search looks in string columns, including strings nested in a dictionary.
  source: S1
  evidence: "searched in the columns of type string , even if the values are nested in a dictionary."
- id: C6
  claim: Row slices require Parquet exports so the whole dataset is not downloaded.
  source: S2
  evidence: "only datasets with parquet exports are supported"
- id: C7
  claim: The rows endpoint takes five query parameters.
  source: S2
  evidence: "The /rows endpoint accepts five query parameters"
- id: C8
  claim: partial true means the dataset was too big to slice in full.
  source: S2
  evidence: "the slices couldn't be run on the full dataset because it's too big."