Hugging Face API: Search Hugging Face Spaces
Finds public Hugging Face Spaces demos for a task, with descriptions, likes, running status and update dates.
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 results by relevance, most_liked, or trending. For example, most_liked.
relevance (default)
One of
relevance,most_liked,trending.- Query, required
query What the app should do, for example, remove image background.
remove image background
- Max Results optional
max_results Maximum number of Spaces to return, for example, 20.
20 (default)
Whole number from 1 to 100.
Input as JSON
{ "query": "remove image background"}Output
{ "spaces": []}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"huggingface.co/search_spaces","input":{"query":"remove image background"}}' # 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_spaces" , "input": { "query": "remove image background" }})# 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_spaces" , "input": { "query": "remove image background" } }), 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_spaces# with {"query":"remove image background"}"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": [ "relevance", "most_liked", "trending" ], "type": "string", "default": "relevance", "description": "Order results by relevance, most_liked, or trending. For example, most_liked." }, "query": { "type": "string", "minLength": 1, "description": "What the app should do, for example, remove image background." }, "max_results": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "description": "Maximum number of Spaces to return, for example, 20.", "x-fous-developer": true } }, "additionalProperties": false}Output schema
{ "type": "object", "required": [ "spaces" ], "properties": { "spaces": { "type": "array", "items": { "type": "object", "required": [ "app_name", "author", "short_description", "likes", "running_now", "last_updated", "app_link", "space_repository_id", "hardware", "app_framework" ], "properties": { "likes": { "type": "integer", "description": "Number of likes." }, "author": { "type": "string", "description": "Name of the publisher." }, "app_link": { "type": "string", "format": "uri", "description": "Link to the app page." }, "app_name": { "type": "string", "description": "Name of the demo app." }, "hardware": { "type": [ "string", "null" ], "description": "Current hardware when running, otherwise requested hardware, if available.", "x-fous-developer": true }, "running_now": { "type": "boolean", "description": "Whether the app is currently running." }, "last_updated": { "type": [ "string", "null" ], "format": "date", "description": "Date the Space was last updated, if available." }, "app_framework": { "type": [ "string", "null" ], "description": "Framework for the Space, if available.", "x-fous-developer": true }, "short_description": { "type": [ "string", "null" ], "description": "Short description of the app, if available." }, "space_repository_id": { "type": "string", "description": "Space repository ID in author/name form." , "x-fous-developer": true } }, "additionalProperties": false }, "description": "Matching public demo apps." } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
huggingface.co/search_spaces- Returns
- app name, author, description, likes, running status, last updated, link, hardware, framework
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_spaces with the inputs above.
Ask your agent
- Find public Spaces that can remove the background from a photo, sorted by most liked
- Show me trending Hugging Face demos for text-to-speech with their running status
- I need a Space that transcribes audio to text; list the top 10 by relevance with hardware info
- Look up Hugging Face Spaces for image upscaling and include last updated dates
- Which Spaces on huggingface.co generate captions for videos? Give me up to 15 results with frameworks
See more
All Hugging Face methodsFinds public Hugging Face models by search words, with an optional task and sort order. License is null when the model does not publish one.
huggingface.co/search_modelsFinds 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_modelsLooks 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_modelSearches 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_postsFinds iPhone and iPad apps by keyword in a chosen country's App Store, with ratings, prices, categories and App Store links.
apps.apple.com/search_appsFinds 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 Android apps on Google Play by keywords, in Play search order, with each listing's developer, star rating, price and currency for the chosen country, download range and link. Results are limited to apps shown on the public search page.
play.google.com/search_apps