Calls the Hugging Face Dataset Viewer HTTP API (datasets-server.huggingface.co) to validate datasets, paginate, search, or filter rows, and list parquet shards. Use when inspecting or extracting rows from Hub datasets without loading them fully. Not for model-card eval tables (hugging-face-evaluation) or training loops. Do not use as a substitute for datasets.load_dataset.
Calls the Hugging Face Dataset Viewer HTTP API (datasets-server.huggingface.co) to validate datasets, paginate, search, or filter rows, and list parquet shards. Use when inspecting or extracting rows from Hub datasets without loading them fully. Not for model-card eval tables (hugging-face-evaluation) or training loops. Do not use as a substitute for datasets.load_dataset.
This skill covers read-only Dataset Viewer API calls against the Hugging Face Hub for dataset exploration and row extraction. It also documents optional upload flows for creating dataset repos and publishing agent session traces. All Dataset Viewer endpoints are GET requests against https://datasets-server.huggingface.co.
When to Use
Use this skill when you need to:
Validate, preview, or paginate rows from a Hugging Face dataset.
Search or filter dataset rows via the Dataset Viewer API.
Discover parquet shard URLs or retrieve dataset size/statistics.
Upload parquet files to a dataset repo (low-dependency CLI flow).
Publish agent session traces (Claude Code, Codex, Pi) to the Hub.
Use response fields num_rows_total, num_rows_per_page, and partial to drive continuation logic. Stop when offset + length >= num_rows_total or when partial indicates the response is truncated.
Response contains per-config/split parquet file URLs. For CLI-based parquet URL discovery or SQL queries, use the hf-cli skill with hf datasets parquet and hf datasets sql.
# Set auth token
$env:HF_TOKEN = "YOUR_KEY"
# Upload parquet folder (auto-creates repo if missing)
npx -y @huggingface/hub upload datasets/YOUR_NAMESPACE/YOUR_REPO ./local/parquet-folder data
# Upload as private repo on creation
npx -y @huggingface/hub upload datasets/YOUR_NAMESPACE/YOUR_REPO ./local/parquet-folder data --private
After upload, call /parquet to discover <config>/<split>/<shard> values for querying.
12. Publish agent session traces
The Hub auto-detects raw agent session traces from Claude Code, Codex, and Pi Agent. Upload them as original JSONL files and the Hub tags the dataset as Traces and enables the trace viewer.
Common local session directories:
Claude Code: ~/.claude/projects
Codex: ~/.codex/sessions
Pi: ~/.pi/agent/sessions
Always default to private dataset repos — traces can contain prompts, file paths, tool outputs, secrets, or PII. Preserve raw .jsonl files and nest them by project/cwd rather than uploading every session at the dataset root.
length exceeds 100: The API caps length at 100 for /rows, /search, and /filter. Requesting more returns at most 100 rows — do not assume you received the full requested count.
Missing config or split: Row-level endpoints require both parameters. Always call /splits first if you do not know them.
Gated/private datasets without auth: Requests silently return 401/403 or empty results. Always pass Authorization: Bearer <HF_TOKEN> for non-public datasets.
URL encoding: Query parameters (especially where, query, dataset) must be URL-encoded. Spaces, &, =, and special characters break the request if not encoded.
partial flag: When /rows returns partial: true, the response is truncated and does not represent all matching rows. Use num_rows_total to determine how many pages remain.
Trace uploads with secrets: Agent traces can embed file contents, API keys, or PII from tool outputs. Always use --private and review contents before uploading.
Flat trace uploads: Uploading all .jsonl files to the dataset root makes the trace viewer hard to navigate. Nest by project or cwd directory.
PowerShell variable expansion: In PowerShell, use $env:HF_TOKEN (not $HF_TOKEN) for environment variable expansion inside double-quoted strings. In single-quoted strings, no expansion occurs.
