Hugging Face APIhuggingface.co ↗
Access Hugging Face Spaces and model listings via API. Filter by trending score, likes, pipeline tag, language, and more. 2 endpoints, structured JSON.
What is the Hugging Face API?
This API provides structured access to Hugging Face data through 2 endpoints covering Spaces and models. The list_top_spaces endpoint returns Space identifiers, authors, like counts, SDK types, tags, and trending scores. The search_models endpoint returns model metadata including pipeline tags, download counts, library names, and language filters — all paginated and sortable by likes, trending score, or recency.
curl -X GET 'https://api.parse.bot/scraper/a413b030-7c3f-46ee-9e26-18d1ac91d384/list_top_spaces?sort=likes&limit=20&offset=0&search=chat&direction=-1' \ -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-co-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: huggingface_co_api_fork SDK — bounded, re-runnable; every call capped."""
from parse_apis.huggingface_co_api import HuggingFace, Sort, ModelSort, Direction, InputFormatInvalid
client = HuggingFace()
# List top Spaces by likes descending, capped at 5 items.
for space in client.spaces.list(sort=Sort.LIKES, direction=Direction.DESCENDING, limit=5):
print(space.title, space.likes, space.sdk)
# Search for chat-related Spaces, take the first result.
top_chat = client.spaces.list(search="chat", limit=1).first()
if top_chat is not None:
print(top_chat.id, top_chat.author, top_chat.created_at)
# Search models by keyword, filter to a specific task.
for model in client.models.search(search="bert", sort=ModelSort.DOWNLOADS, filter="fill-mask", limit=3):
print(model.model_name, model.downloads, model.pipeline_tag)
# Drill into the top trending model.
top_model = client.models.search(sort=ModelSort.TRENDING_SCORE, limit=1).first()
if top_model is not None:
print(top_model.id, top_model.author, top_model.likes)
# Typed error: catch an invalid-input error around a bad sort value.
try:
for s in client.spaces.list(sort="bad_value", limit=1):
print(s.title)
except InputFormatInvalid as e:
print("invalid input:", e)
print("exercised: spaces.list / models.search")
List Spaces ranked by the chosen sort criterion. Each Space includes its identifier, title, author, like count, SDK, tags, and timestamps. Results are returned as a single page; pass offset to advance manually. When sort is trendingScore, each item also carries its trending_score.
| Param | Type | Description |
|---|---|---|
| sort | string | Ranking criterion for the returned list. |
| limit | integer | Number of Spaces to return per page (1–100). |
| offset | integer | Number of items to skip for pagination. |
| search | string | Free-text filter applied to Space names and descriptions. Omit to return all Spaces. |
| direction | string | Sort direction: -1 for descending, 1 for ascending. |
{
"type": "object",
"fields": {
"spaces": "array of Space objects sorted by the chosen criterion"
},
"sample": {
"spaces": [
{
"id": "enzostvs/deepsite",
"sdk": "docker",
"tags": [
"docker",
"region:us"
],
"likes": 16617,
"title": "Generate any application by Vibe Coding it",
"author": "enzostvs",
"created_at": "2025-03-26T19:26:05.000Z",
"last_modified": "2026-02-06T12:47:43.000Z"
}
]
}
}About the Hugging Face API
Spaces Discovery
The list_top_spaces endpoint returns a ranked list of Hugging Face Spaces with up to 100 results per call. Each Space object includes its full identifier, title, author username, like count, SDK (Gradio, Streamlit, etc.), tags, and creation/update timestamps. When sort is set to trendingScore, each object also includes a trending_score field. Use the offset parameter to paginate manually through the full catalog, and the search parameter to filter by name or description text. direction accepts -1 for descending or 1 for ascending order.
Model Search and Filtering
The search_models endpoint surfaces Hugging Face model entries with per-model fields: identifier, author, model name, like count, download count, pipeline tag, library name, tags, language codes, and timestamps. The filter parameter accepts pipeline task strings such as text-generation, image-classification, or fill-mask to narrow results by ML task. The language parameter accepts ISO language codes like en, fr, or zh. Like list_top_spaces, results support manual pagination via offset and accept a sort parameter including trending score.
Pagination and Sorting Behavior
Both endpoints return a single page of results rather than a cursor-based stream. To walk through large result sets, increment offset by the value of limit on each successive call. The limit parameter accepts integers from 1 to 100. Sorting by trendingScore is the most volatile criterion — values shift as community activity changes — while sorting by likes or update timestamp gives more stable rankings for archival or monitoring use cases.
The Hugging Face API is a managed, monitored endpoint for huggingface.co — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when huggingface.co 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.co 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?+
- Track which Hugging Face Spaces are gaining traction by polling trending_score changes over time
- Build a model discovery tool filtered by pipeline tag (e.g. text-generation) and sorted by download count
- Monitor community adoption of specific ML libraries by filtering search_models results by library_name
- Identify top-liked Spaces for a given SDK like Gradio or Streamlit using the tags and sort fields
- Aggregate language-specific model availability by querying search_models with different language codes
- Surface recently updated Spaces by sorting list_top_spaces by lastModified in descending order
- Compare like counts and download counts across authors to analyze model creator influence
| 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 list_top_spaces return when sort is set to trendingScore?+
trending_score field in addition to the standard fields (identifier, title, author, like count, SDK, tags, timestamps). This field is absent when sorting by other criteria such as likes or recency.Can I filter search_models by both pipeline tag and language at the same time?+
filter parameter (for pipeline task) and the language parameter are independent and can be combined in a single request. For example, passing filter=text-generation and language=fr returns French-language text generation models sorted by your chosen criterion.Does the API expose dataset listings or model cards?+
list_top_spaces and model metadata via search_models. Dataset listings, model card markdown, and file-level repository contents are not returned. You can fork this API on Parse and revise it to add an endpoint targeting Hugging Face dataset entries.How does pagination work across both endpoints?+
limit to offset on each subsequent request. The maximum limit per request is 100 items.