Hugging Face APIhuggingface.co ↗
Retrieve ranked Hugging Face Spaces by likes, trending score, or recency. Filter by search query, paginate with offset, and get SDK, tags, and author data.
What is the Hugging Face API?
The Hugging Face Spaces API exposes 1 endpoint — list_top_spaces — that returns an array of Space objects covering 9 fields including title, author, like count, SDK, tags, and timestamps. You can sort results by trending score, likes, or creation date, and narrow them with a free-text search filter to find specific demos or tools published on huggingface.co.
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 SDK — bounded, re-runnable; every call capped."""
from parse_apis.huggingface_co_api import HuggingFace, Sort, Direction, InvalidInput
client = HuggingFace()
# List top Spaces by likes (default sort), capped at 3 items.
for space in client.spaces.list(sort=Sort.LIKES, direction=Direction.DESCENDING, limit=3):
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:
print(top_chat.id, top_chat.author, top_chat.created_at)
# 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 InvalidInput as e:
print("invalid input:", e)
print("exercised: spaces.list")
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
What the API Returns
The list_top_spaces endpoint returns a paginated list of Hugging Face Spaces, each represented as a Space object. Each object includes the Space's unique identifier, display title, author username, like count, SDK (e.g. Gradio, Streamlit, Docker, or static), an array of tags, and created/updated timestamps. When you sort by trendingScore, each item also carries a trending_score numeric field that reflects the platform's trending algorithm output.
Sorting, Filtering, and Pagination
The sort parameter accepts values like likes, trendingScore, or createdAt, letting you target whichever ranking axis matters for your use case. Pair sort with direction (-1 for descending, 1 for ascending) to flip the order. The search parameter applies a free-text filter against Space names and descriptions — omit it to return the full ranked list. Results are returned as a single page; use limit (1–100) and offset to advance through the list manually.
Coverage and Scope
The API covers publicly visible Spaces on huggingface.co. Each response reflects the current state of the Space index: like counts and trending scores change as community activity shifts. The sdk field tells you whether a Space runs on Gradio, Streamlit, Docker, or a static deployment, which is useful for filtering by interaction type. Tags vary widely — from NLP and computer-vision to audio and code — and are returned as a raw array for downstream filtering.
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 ML demo Spaces are gaining traction by sorting on trendingScore and polling daily.
- Build a directory of Gradio-based Spaces by filtering the sdk field from list_top_spaces results.
- Identify prolific authors by aggregating the author field across the top-liked Spaces.
- Discover recently published Spaces by sorting on createdAt in descending order.
- Search for domain-specific tools (e.g. 'speech' or 'diffusion') using the search parameter.
- Monitor like count growth over time by storing snapshots of top Spaces and comparing like fields.
- Categorize Spaces by tag for a curated ML tools index using the tags array in each response.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.