Hugging Face Hub API
Free model hub API with no key: search over a million models by task, library or tag, with download counts, likes and a trending score. Tested example included.
Endpoint tested and returned HTTP 200 on 2026-08-21
What is the Hugging Face Hub API?
The Hugging Face Hub exposes its model, dataset and Space catalogues through a public API needing no key for public repositories. Model search returns the repository id, download and like counts, tags, pipeline task and a trending score.
Every serious machine learning project ends up querying this catalogue eventually — to check whether a model exists, what task it is registered for, which library loads it, or simply how widely used it is. Public repositories need no token at all, which makes the Hub one of the more genuinely open large catalogues on the web.
The `tags` array is doing more work than it looks. It mixes framework support (`pytorch`, `onnx`, `safetensors`), architecture (`bert`), task (`feature-extraction`), language codes and the training datasets a model was built on, all in one flat list. Filtering on `library_name` or `pipeline_tag` is more reliable than pattern-matching tags. Note the difference between `downloads`, which counts the last thirty days rather than all time, and `trendingScore`, which is a momentum figure — a venerable model with a quarter of a billion downloads can have a trending score near zero, and that is not a contradiction.
Quick facts
- Base URL
https://huggingface.co/api- Authentication
- No token needed for public repositories. Private or gated repositories require a user access token in an Authorization header.
- Rate limit
- Not published as a fixed figure. Anonymous traffic is throttled more tightly than authenticated traffic.
- Pricing
- Free. The Hub is free to browse; paid plans cover private storage and compute.
- CORS
- Enabled — callable directly from browser JavaScript
- Official docs
- Read the docs
How to use the Hugging Face Hub API
Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.
1. Search the model hub by download count
GET https://huggingface.co/api/models?limit=2&sort=downloads&direction=-1
curl 'https://huggingface.co/api/models?limit=2&sort=downloads&direction=-1'const res = await fetch("https://huggingface.co/api/models?limit=2&sort=downloads&direction=-1");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);import requests
res = requests.get("https://huggingface.co/api/models?limit=2&sort=downloads&direction=-1", timeout=20)
res.raise_for_status()
print(res.json())[
{
"_id": "621ffdc136468d709f180294",
"id": "sentence-transformers/all-MiniLM-L6-v2",
"likes": 5230,
"private": false,
"downloads": 257827147,
"tags": [
"sentence-transformers",
"pytorch",
"tf",
"rust",
"onnx",
"safetensors",
"openvino",
"bert",
"feature-extraction",
"sentence-similarity",
"transformers",
"en",
"dataset:s2orc",
"dataset:flax-sentence-embeddings/stackexchange_xml",
"dataset:ms_marco",
"dataset:gooaq",
"dataset:yahoo_answers_topics",
"dataset:code_search_net",
"dataset:search_qa",
"dataset:eli5",
"dataset:snli",
"dataset:multi_nli",
"dataset:wikihow",
"dataset:natural_questions",
"dataset:trivia_qa",
"dataset:embedding-data/sentence-compression",
"dataset:embedding-data/flickr30k-captions",
"dataset:embedding-data/altlex",
"dataset:embedding-data/simple-wiki",
"dataset:embedding-data/QQP",
"dataset:embedding-data/SPECTER",
"dataset:embedding-data/PAQ_pairs",
"dataset:embedding-data/WikiAnswers",
"arxiv:1904.06472",
"arxiv:2102.07033",
"arxiv:2104.08727",
"arxiv:1704.05179",
"arxiv:1810.09305",
"base_model:nreimers/MiniLM-L6-H384-uncased",
"base_model:quantized:nreimers/MiniLM-L6-H384-uncased",
"license:apache-2.0",
"eval-results",
"text-embeddings-inference",
"endpoints_compatible",
"region:us",
"deploy:sagemaker",
"deploy:azure"
],
"pipeline_tag":Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | query | Optional | How many results to return. 2 |
sort | query | Optional | Field to sort by, such as `downloads`, `likes`, `createdAt` or `trendingScore`. downloads |
direction | query | Optional | Set `-1` for descending. Ascending is the default, which is rarely what you want. -1 |
search | query | Optional | Free-text search across repository names. bert |
filter | query | Optional | Filter by tag, library or task. text-classification |
full | query | Optional | Set true to include the full repository metadata, including files and config. true |
/datasets | path | Optional | The same query grammar against the dataset catalogue instead of models. |
Response fields
id / modelIdstring- Repository identifier in `owner/name` form. Both fields carry the same value.
_idstring- Internal database identifier. Use `id` for anything you store.
downloadsinteger- Downloads over the last thirty days, not all time. A very large figure means current heavy use.
likesinteger- Community likes, an all-time count.
trendingScorefloat- Momentum indicator. Near zero for established models that are widely used but no longer rising.
privateboolean- Always false in anonymous results, since private repositories are not returned without a token.
tagsarray- Flat list mixing frameworks, architecture, task, language codes and source datasets. Prefer `library_name` and `pipeline_tag` for reliable filtering.
pipeline_tagstring- The task the model is registered for, such as `feature-extraction` or `text-generation`.
library_namestring- Library that loads the model — `transformers`, `sentence-transformers`, `diffusers` and so on.
createdAtstring- Repository creation timestamp.
What you can build with the Hugging Face Hub API
- Find the most-downloaded model for a specific task
- Check which library and task a model is registered for before loading it
- Build an internal catalogue of approved models
- Track adoption of a model family over time
Common errors and how to fix them
Results sorted the wrong way
Sorting defaults to ascending.
Fix: Add `direction=-1`. Without it, sorting by downloads returns the least-used models.
Repository not found
It is private, gated, or the name is wrong.
Fix: Gated repositories need a token and licence acceptance. Anonymous requests see public repositories only.
Download counts lower than expected
`downloads` is a thirty-day window.
Fix: It is not a cumulative total. Compare like with like when ranking models.
Throttled
Anonymous traffic is limited more tightly than authenticated.
Fix: Cache results and reduce polling, or authenticate with a free user access token.
Hugging Face Hub API — frequently asked questions
Do I need a token for the Hugging Face API?
Not for public models, datasets and Spaces. A user access token is only needed for private or gated repositories, and for higher rate limits.
What does the downloads figure cover?
The last thirty days, not all time. It is a usage-intensity measure rather than a lifetime total, which is why it can drop for a model that is still popular.
How is trendingScore different from downloads?
It measures momentum rather than volume. A long-established model with enormous download counts can have a trending score near zero simply because it is no longer rising.
How do I filter by task?
Use `filter` with a pipeline tag, or read `pipeline_tag` on the results. Filtering on the free-form `tags` array is unreliable because it mixes several different kinds of label.
Tools that pair with this API
JSON Formatter
Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.
CSV Column Statistics Calculator
Profile a CSV column by column: type, blanks, distinct values, min, max, mean, median, standard deviation and percentiles, plus top values — all in-browser.
Keyword Extractor (RAKE)
Pull the key phrases out of any text with the RAKE algorithm. Ranks multi-word phrases by co-occurrence score, entirely in your browser.
Hugging Face Hub is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.