Hugging Face APIhuggingface.com ↗
Search Hugging Face public model repositories by keyword, tag, and author. Fetch full metadata including stats, license, architecture, and MoE config fields.
What is the Hugging Face API?
This API exposes 2 endpoints covering the Hugging Face public model hub: search_models for filtering and paginating model repositories by keyword, tag, author, and sort order, and get_model for retrieving full metadata on a single repository. A single get_model response includes over 15 distinct fields — commit SHA, like count, safetensors parameter counts, license, language list, gating status, architecture details, and MoE-specific config values such as num_experts_per_tok.
curl -X GET 'https://api.parse.bot/scraper/935de92c-492e-4400-b2e5-7079e64018cd/search_models?tags=text-generation&limit=5&query=moe' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace huggingface-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Hugging Face Models API — search, drill down, point lookup."""
from parse_apis.huggingface_com_api import HuggingFace, ModelSort, SortDirection, ModelNotFound
client = HuggingFace()
# Search for mixture-of-experts text-generation models, sorted by downloads.
for summary in client.model_summaries.search(
query="moe", tags="text-generation", sort=ModelSort.DOWNLOADS,
direction=SortDirection.DESC, limit=5,
):
print(summary.model_id, summary.downloads, summary.likes)
# Drill down: take the top hit and fetch its full metadata.
top = client.model_summaries.search(
query="moe", tags="text-generation", sort=ModelSort.DOWNLOADS, limit=1,
).first()
if top is not None:
model = top.details()
print(model.model_id, model.license, model.model_type)
print("architectures:", model.architectures)
print("params:", model.safetensors_total_params)
print("files:", model.files[:5])
# Point lookup by a known repository id discovered above.
if top is not None:
try:
full = client.models.get(model_id=top.model_id)
print(full.model_id, full.author, full.downloads, full.used_storage_bytes)
except ModelNotFound:
print("model not found or private")
print("exercised: model_summaries.search / details / models.get")
Searches public model repositories on the Hugging Face hub. One round trip returns up to `limit` model summaries (name substring match on `query`, optional tag filters and author restriction), ordered by the chosen sort key. Results are cursor-paginated: when more models exist, `next_cursor` is set and `has_more` is true; pass `next_cursor` back as `cursor` with the same other parameters to fetch the following page. Omitting `cursor` returns the first page. A query with no matching models returns an empty `models` list with `has_more` false. `trending_score` is the hub's trending metric and may be 0.
| Param | Type | Description |
|---|---|---|
| sort | string | Ranking key for the result stream. |
| tags | string | Comma-separated hub tag filters that every returned model must carry, e.g. text-generation,moe. Tags include pipeline tasks (text-generation), libraries (transformers), languages (en) and license:<id>. Omitted = no tag filter. |
| limit | integer | Models per page, 1-100; larger values are clamped to 100. |
| query | string | Free-text search matched against model names (e.g. moe, mixtral). Omitted = no keyword restriction. |
| author | string | Restrict results to models owned by this user or organization (e.g. mistralai). Omitted = all authors. |
| cursor | string | Opaque continuation token from a previous response's next_cursor. Omitted = first page. |
| direction | string | Sort direction. |
{
"type": "object",
"fields": {
"count": "number of models in this page",
"models": "array of model summaries: model_id (repo id usable with get_model), author, pipeline_tag, library_name, tags (array of hub tag strings), downloads (last-30-day count), likes, trending_score, gated (boolean or null), private, created_at / last_modified (ISO 8601 UTC), url",
"has_more": "boolean, true when next_cursor is set",
"next_cursor": "opaque token for the next page, or null when exhausted"
},
"sample": {
"data": {
"count": 1,
"models": [
{
"url": "https://huggingface.co/Qwen/Qwen1.5-MoE-A2.7B",
"tags": [
"transformers",
"safetensors",
"qwen2_moe",
"text-generation",
"pretrained",
"moe",
"conversational",
"en",
"license:other",
"endpoints_compatible",
"region:us"
],
"gated": false,
"likes": 229,
"author": "Qwen",
"private": false,
"model_id": "Qwen/Qwen1.5-MoE-A2.7B",
"downloads": 508459,
"created_at": "2024-02-29T04:52:16.000Z",
"library_name": "transformers",
"pipeline_tag": "text-generation",
"last_modified": "2024-04-18T11:58:22.000Z",
"trending_score": 0
}
],
"has_more": true,
"next_cursor": "eyIkb3IiOlt7..."
},
"status": "success"
}
}About the Hugging Face API
Searching Models
The search_models endpoint accepts up to seven parameters. The query string matches against model names — useful for terms like mixtral or moe. The tags parameter takes a comma-separated list of hub tag strings (e.g. text-generation,moe), and every returned model must carry all of them. author restricts results to a specific user or organization such as mistralai. The sort and direction parameters control ranking order, and limit caps page size between 1 and 100. Each page response includes a models array of summaries with model_id, author, pipeline_tag, library_name, tags, and download/like counts.
Pagination
Results are cursor-paginated. When has_more is true, the response carries a next_cursor token. Pass that token as the cursor parameter on the next call to retrieve the following page. When next_cursor is null, the result set is exhausted. This design works well for iterating large tag-filtered sets (e.g. all public MoE models) without offset drift.
Full Model Metadata
The get_model endpoint takes a model_id in <author>/<name> form — exactly as returned by search_models — and returns a detailed record. Fields cover hub statistics (likes, sha, url), content (files, tags, license, private, gated), provenance (author, spaces — up to 50 Space IDs using this model), and architecture data from the repo config. For mixture-of-experts models, num_experts_per_tok is populated; for all others it is null.
The Hugging Face API is a managed, monitored endpoint for huggingface.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when huggingface.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official huggingface.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Cataloging all public MoE models by filtering
search_modelswith themoetag and iterating with cursor pagination - Building a model leaderboard by sorting
search_modelsresults by downloads or likes across a specificauthor - Auditing license compliance by bulk-fetching
licensefields viaget_modelfor a list of model IDs - Tracking which Spaces depend on a given model using the
spacesarray returned byget_model - Identifying gated or private models in a curated list by checking the
gatedandprivatefields fromget_model - Filtering text-generation models from a specific organization for a model picker UI using
authorandtagstogether insearch_models
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Hugging Face have an official developer API?+
What does `get_model` return for mixture-of-experts models specifically?+
get_model response populates num_experts_per_tok from the repo config. For all other model types this field is null. Other architecture fields such as model type are returned regardless of architecture.Does `search_models` return dataset or Space repositories in addition to models?+
search_models returns model repositories only. The model_id, pipeline_tag, and library_name fields are model-hub specific. Dataset and Space repository search are not currently covered. You can fork this API on Parse and revise it to add endpoints for those repository types.Is there a limit on how many Spaces are listed per model in `get_model`?+
spaces array returns at most 50 Space IDs that reference the model. Models used by more than 50 Spaces will have the list truncated at that cap.Does the API expose model card content such as README text or evaluation results tables?+
license, tags, files, and architecture config, but the free-text model card body and embedded evaluation tables are not included. You can fork this API on Parse and revise it to add a model card content endpoint.