Hugging Face API: Search models
Finds public Hugging Face models by search words, with an optional task and sort order. License is null when the model does not publish one.
Unofficial. Not affiliated with or endorsed by Hugging Face.
Inputs
Values from the run on Oct 23, 2026, shown under Output.
- Sort optional
sort Order of results; for example "trending". Defaults to most_downloaded.
most_downloaded (default)
One of
most_downloaded,most_liked,trending,recently_updated.- Task optional
task Task in plain words, such as "text generation", "image classification", or "sentiment analysis". Defaults to all tasks.
all tasks (default)
- Query, required
query Search words for model names, such as "whisper" or "sentiment analysis".
llama
- Max Results optional
max_results Maximum models to return, for example 20; at most 100.
100
Whole number from 1 to 100. Default
20.
Input as JSON
{ "query": "llama", "max_results": 100}Output
{ "models": [ { "task": "Text Generation", "likes": 8563, "author": "meta-llama", "license": "llama3.1", "model_name": "Llama-3.1-8B-Instruct", "repository_id": "meta-llama/Llama-3.1-8B-Instruct" , "model_page_link": "https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct" , "last_updated_date": "2024-09-25", "downloads_last_30_days": 4864172 }, { "task": "Text Generation", "likes": 1883, "author": "meta-llama", "license": "llama3.2", "model_name": "Llama-3.2-1B-Instruct", "repository_id": "meta-llama/Llama-3.2-1B-Instruct" , "model_page_link": "https://huggingface.co/meta-llama/Llama-3.2-1B-Instruct" , "last_updated_date": "2024-10-24", "downloads_last_30_days": 3970913 }, { "task": "Text Classification", "likes": 428, "author": "meta-llama", "license": "llama3.1", "model_name": "Prompt-Guard-86M", "repository_id": "meta-llama/Prompt-Guard-86M" , "model_page_link": "https://huggingface.co/meta-llama/Prompt-Guard-86M" , "last_updated_date": "2025-11-12", "downloads_last_30_days": 2376548 } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"huggingface.co/search_models","input":{"query":"llama","max_results":100}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "huggingface.co/search_models" , "input": { "query": "llama", "max_results": 100 }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "huggingface.co/search_models" , "input": { "query": "llama", "max_results": 100 } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run huggingface.co/search_models# with {"query":"llama","max_results":100}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "query" ], "properties": { "sort": { "enum": [ "most_downloaded", "most_liked", "trending", "recently_updated" ], "type": "string", "default": "most_downloaded", "examples": [ "trending" ], "description": "Order of results; for example \"trending\". Defaults to most_downloaded." }, "task": { "type": "string", "default": "all tasks", "examples": [ "text generation" ], "description": "Task in plain words, such as \"text generation\", \"image classification\", or \"sentiment analysis\". Defaults to all tasks." }, "query": { "type": "string", "examples": [ "whisper" ], "minLength": 1, "description": "Search words for model names, such as \"whisper\" or \"sentiment analysis\"." }, "max_results": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "examples": [ 20 ], "description": "Maximum models to return, for example 20; at most 100.", "x-fous-developer": true } }, "additionalProperties": false}Output schema
{ "type": "object", "required": [ "models" ], "properties": { "models": { "type": "array", "items": { "type": "object", "required": [ "model_name", "author", "task", "downloads_last_30_days", "likes", "last_updated_date", "license", "model_page_link", "repository_id" ], "properties": { "task": { "type": [ "string", "null" ], "description": "Model task in words." }, "likes": { "type": [ "integer", "null" ], "description": "Total likes." }, "author": { "type": [ "string", "null" ], "description": "Publisher or organization." }, "license": { "type": [ "string", "null" ], "description": "License as stated by the model publisher." }, "model_name": { "type": "string", "description": "Model repository name." }, "repository_id": { "type": "string", "description": "Repository ID (author/name)." , "x-fous-developer": true }, "model_page_link": { "type": "string", "format": "uri", "description": "Hugging Face model page." }, "last_updated_date": { "type": [ "string", "null" ], "format": "date", "description": "Most recent update date." }, "downloads_last_30_days": { "type": [ "integer", "null" ], "description": "Downloads over the last 30 days." } }, "additionalProperties": false }, "description": "Matching models in the requested order." } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
huggingface.co/search_models- Returns
- model name, author, task, downloads last 30 days, likes, last updated date, license, model page link, repository ID
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method huggingface.co/search_models with the inputs above.
Ask your agent
- Find the most downloaded speech recognition models on Hugging Face, top 10 please
- Which open models for image classification are trending right now?
- I need text generation models with an Apache license, sorted by likes
- Show me recently updated sentiment analysis models on huggingface.co
- List 50 models matching whisper, ordered by most liked
See more
All Hugging Face methodsFinds public Hugging Face datasets by name or topic, ordered by downloads, likes, trending score or last update.
huggingface.co/search_datasetsLists Hugging Face models in trending order this week, optionally filtered to one task. Downloads cover the last 30 days.
huggingface.co/list_trending_modelsFinds public Hugging Face Spaces demos for a task, with descriptions, likes, running status and update dates.
huggingface.co/search_spacesLooks up one Hugging Face model by name, repository ID or link and returns its public details, model card summary and file sizes. For a name, the first matching model is returned.
huggingface.co/get_modelLists public OpenRouter models with per-million-token prices, context size, input types, release date and model page. Results can be sorted by newest, input price or popularity.
openrouter.ai/list_modelsFinds public Kaggle datasets on a topic, with size, file formats, usability, popularity and license. Lists at most 100 results in Kaggle's order; files are not downloaded.
kaggle.com/search_datasetsFinds Rust crates on crates.io by keywords, sorted by relevance, total downloads, recent downloads, or newest creation.
crates.io/search_cratesSearches public Bluesky posts for words, optionally ordered by latest or top and filtered by date, author or language. Search indexing may lag behind new posts.
bsky.app/search_posts