← All notes

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."

@misc{iil_note_sf4ds1c1,
  author = {{iinventedlight}},
  title = {{Using the Dataset Viewer API}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-03},
  url = {https://iinventedlight.com/library/notes/hf-dataset-viewer-api/},
  note = {Permanent ID iil:note:sf4ds1c1. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/hf-dataset-viewer-api.md.