# Hugging Face Hub Search: Models, Datasets, Spaces (`conserving_celerytop/huggingface-hub-search-api`) Actor

Search the Hugging Face Hub for models, datasets, Spaces and daily papers. Get flat rows with downloads, likes, task, license, language, tags and dates. Filter by owner, task, license and language. Public metadata, $3.00 per 1,000 results.

- **URL**: https://apify.com/conserving_celerytop/huggingface-hub-search-api.md
- **Developed by:** [Don Mangu](https://apify.com/conserving_celerytop) (community)
- **Categories:** AI, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.10 / 1,000 search results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Hugging Face Hub Search: Models, Datasets, Spaces

Hugging Face Hub search that returns one flat row per model, dataset, Space or daily paper: downloads, likes, task, license, language, tags and dates, ready for a spreadsheet, a database or an AI agent. Pick a resource type, add search text or filters, set a maximum and run. Results cost $3.00 per 1,000 rows, and a run of 20 rows costs about six cents. I built this Actor as an independent developer. It is not affiliated with or endorsed by Hugging Face.

### Sample output

One row from a Hugging Face API model search (task `text-generation`, sorted by downloads). Values were read from the Hub on 2026-10-04 and change over time. Fields with no value (`null`) are left out here for space.

```json
{
  "rank": 1,
  "recordType": "model",
  "id": "Qwen/Qwen3-0.6B",
  "owner": "Qwen",
  "name": "Qwen3-0.6B",
  "url": "https://huggingface.co/Qwen/Qwen3-0.6B",
  "task": "text-generation",
  "library": "transformers",
  "license": "apache-2.0",
  "downloads": 29665992,
  "downloadsAllTime": 234340865,
  "likes": 1727,
  "trendingScore": 31,
  "parameters": 751632384,
  "gated": false,
  "createdAt": "2025-04-27T03:40:08.000Z",
  "lastModified": "2025-07-26T03:46:27.000Z",
  "tags": ["transformers", "safetensors", "qwen3", "text-generation", "license:apache-2.0"]
}
```

### How to search the Hugging Face Hub with this Actor

1. Open the Actor and choose a **Resource type**: Models, Datasets, Spaces or Daily papers.
2. Type **Search text** to match repository names, for example `llama` or `sentiment`. Leave it empty to list the top results for your sort order. For papers, type a topic such as `diffusion`.
3. Set **Maximum results**. The prefill is 20, so the first run is cheap. One run returns up to 10,000 rows.
4. Open **Filters** to narrow by owner (for example `meta-llama`), task, license, language, library or Space SDK.
5. Open **Advanced options** to change the sort order, add raw Hub tags or pick a paper date.
6. Click Start. Rows appear in the dataset as they are saved. Use the Overview table, or export to JSON, CSV or Excel.

You can also call the Actor from code through the Apify API. The example below lists the 100 most liked Gradio Spaces.

```bash
curl -X POST "https://api.apify.com/v2/acts/conserving_celerytop~huggingface-hub-search-api/run-sync-get-dataset-items" \
  -H "Authorization: Bearer <YOUR_APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"resource": "spaces", "spaceSdk": "gradio", "sortBy": "likes", "maxItems": 100}'
```

### What data you get from the Hugging Face API

| Field | Applies to | Meaning |
|---|---|---|
| `rank`, `recordType`, `id`, `url` | all | Position in the result, type, repository id such as `owner/name`, and the Hub link |
| `owner`, `name` | models, datasets, Spaces | The namespace and repository name from the id |
| `task`, `library`, `parameters` | models | Pipeline tag, library name and total parameter count when the repository lists it |
| `task`, `description` | datasets | First task category (or the one you filtered by) and a short cleaned description |
| `license`, `languages`, `tags` | models, datasets, Spaces | License id, language codes and the full tag list |
| `downloads`, `downloadsAllTime` | models, datasets | Downloads in the last 30 days and over all time |
| `likes`, `trendingScore` | models, datasets, Spaces | Likes and the Hub trending score |
| `gated` | models, datasets | `false`, `auto` or `manual` access setting |
| `sdk`, `runtimeStage`, `hardware` | Spaces | SDK, current stage and hardware name |
| `title`, `description`, `upvotes`, `numComments`, `organization`, `githubRepo`, `githubStars`, `projectPage`, `publishedAt`, `arxivUrl`, `aiSummary`, `keywords` | papers | Paper title, abstract, community counts, linked code and project page |
| `createdAt`, `lastModified`, `fetchedAt` | all | Hub dates and the time the row was read |

Fields that do not apply to a resource type are `null` or an empty list, so every row has the same columns. When a repository lists several licenses or task categories, the one you filtered by is shown, and all of them stay in `tags`.

### Hugging Face Hub search pricing

Pricing is pay per event. One event is **one saved result row**, plus the standard Actor start event.

| Plan | Price per result | Price per 1,000 results |
|---|---|---|
| Free | $0.0030 | $3.00 |
| Bronze | $0.0027 | $2.70 |
| Silver | $0.0024 | $2.40 |
| Gold | $0.0021 | $2.10 |

Worked example: a search for the 500 most downloaded text-generation models returns 500 rows. On the Free plan that is 500 x $0.003 = $1.50, plus $0.00005 for the Actor start, so about $1.50 in total. The same run on the Gold plan costs $1.05.

How charging works:

- A row is charged only after it is saved to the dataset.
- A valid search with no matches saves one message row and charges one result.
- A search the Hub rejects returns one error row with the Hub message and charges one result.
- Input the Actor rejects before any request (for example a Maximum results of 0) ends the run with a plain message and charges nothing.
- When Hugging Face is unavailable or its rate limit is used up and no rows were saved, the run saves one error row and charges one result. Rows saved before such a stop are charged as usual.
- The run stops when the maximum charge you set for the run is reached.

### Input example

```json
{
  "resource": "datasets",
  "searchQuery": "sentiment",
  "task": "text-classification",
  "license": "mit",
  "language": "en",
  "sortBy": "downloads",
  "maxItems": 200
}
```

| Field | Type | Notes |
|---|---|---|
| `resource` | select | `models`, `datasets`, `spaces` or `papers` |
| `searchQuery` | text | Matches repository names. For papers it runs the Hub paper search |
| `maxItems` | integer | 1 to 10,000. A paper search returns up to 120 |
| `owner`, `task`, `license`, `language`, `library`, `spaceSdk` | text or select | Filters that combine with AND |
| `sortBy` | select | `downloads`, `likes`, `trendingScore`, `createdAt`, `lastModified`. The default is downloads for models and datasets, likes for Spaces, the Hub's newest-first order for papers |
| `tags` | list | Raw Hub tags such as `size_categories:1M<n<10M` |
| `paperDate` | text | `YYYY-MM-DD`, for the daily papers feed |
| `onlyNew` | checkbox | Return only items this monitor has not delivered before. The first run returns everything and becomes the baseline. See Run it every day |
| `monitorName` | text | Names the memory of the monitor. Use one name per saved task. Letters, numbers, `-` and `_`, up to 40 characters |

### Output example for a daily paper

```json
{
  "rank": 1,
  "recordType": "paper",
  "id": "2609.22753",
  "url": "https://huggingface.co/papers/2609.22753",
  "title": "Replacing Large Language Models with Jev Decision Models for Low-Latency Edge Service Orchestration",
  "upvotes": 5,
  "numComments": 2,
  "githubRepo": "https://github.com/OniReimu/Edge-Computing-JEV",
  "publishedAt": "2026-09-26T00:00:00.000Z",
  "arxivUrl": "https://arxiv.org/abs/2609.22753"
}
```

Paper rows leave out author names, submitter profiles and avatars.

### Use cases for a Hugging Face model and dataset list

- Build a catalog of open models by task, license and library, for example every `apache-2.0` text-generation model with more than 100,000 downloads.
- Track trending models, datasets and Spaces each week with a scheduled run sorted by trending score.
- Compare model families by downloads, likes and parameter count.
- Collect dataset candidates for a task and language, with license and size tags.
- Feed daily papers with their linked code repositories into a reading list or an AI agent.

### Run it every day

Switch on **Only new since the last run** and the Actor returns only models, datasets, Spaces or papers that it has not delivered before.

1. Fill the input, for example your search text and filters. Set **Sort by** to Newest created, so new repositories come first.
2. Switch on **Only new since the last run** and enter a **Monitor name**, for example `new-llama-models`. Use one name per saved task.
3. Click **Save as task** and run it once. The first run returns up to **Maximum results** items and becomes the baseline.
4. In the Apify Console, open **Schedules**, click **Create new**, pick your Task, and enter a cron expression for once a day, for example `0 7 * * *`.

Each later run returns only items that are not in the memory. Items skipped as already seen are not charged and do not count toward Maximum results. Items that were cut by Maximum results or by your maximum charge are not remembered, so a later run delivers them. If a search matches more items than Maximum results, the next run continues with the older items you have not received yet. Set Maximum results above the number of new items you expect per day.

The Actor stops reading after 500 items in a row that it delivered before. A run with nothing new reads one page of 500 items and ends with the message "No new items since the last run".

The memory lives in your own key-value store, named `hf-monitor-<monitor name>`. It holds ids only, such as `model|meta-llama/Llama-3.1-8B`. If you change the resource type, search text or any filter, the Actor starts a separate memory for that search, and its first run returns everything again. Maximum results is not part of the memory key.

Worked cost example on the Free plan, with the prices in the pricing table above ($0.003 per row, $0.00005 for the start). Say 40 new models match your search each day. A day costs 40 x $0.003 = $0.12 plus $0.00005, so $0.12005. Thirty days cost 30 x $0.12005 = $3.6015. A day with no new model costs only the start fee of $0.00005. The same search run daily without Only new, with Maximum results 1,000, returns up to 1,000 rows every day: 1,000 x $0.003 = $3.00 plus $0.00005 per day, and 30 days cost 30 x $3.00005 = $90.0015. The 40 new models per day is an example, not a measured value.

### Related Actors

- [Crossref Works Search](https://apify.com/conserving_celerytop/crossref-works-search) finds papers, DOIs and citation counts from the Crossref index.
- [AI Jobs Search](https://apify.com/conserving_celerytop/ai-jobs-search) lists LLM and machine learning jobs from company career pages.

### FAQ

#### Is it legal to list Hugging Face models and datasets with this Actor?

The Actor reads the public Hub API without a login. It returns metadata only: repository names, counts, tags, license ids and dates. It does not download model files or dataset contents, it does not read private repositories, and it does not collect user profiles. The Hugging Face Terms of Service say that content carrying a license "is intended to remain under the terms of such license when further accessed, distributed, or used". The `license` field shows what each repository declares, so check it before you use a model or dataset. This is not legal advice.

#### Which Hugging Face API endpoints does it use?

The public list endpoints for models, datasets and Spaces, plus the daily papers and paper search endpoints. It sends one request per page of up to 1,000 rows and follows the next-page link the Hub returns.

#### What are the limits?

- Up to 10,000 rows per run. Start another run with a narrower filter or a different sort to go further.
- A paper search returns up to 120 rows. The daily papers feed has no such cap.
- Search text matches repository names, not README text.
- The Hub applies an anonymous quota of 500 API calls per 5 minutes per IP address. A 10,000-row run uses 10 calls.
- `downloads` counts the last 30 days. `downloadsAllTime` counts every download.

#### Why did my run stop early or return fewer rows?

Open the `STATS` record in the key-value store. The `status` field says why: `succeeded`, `no_results`, `invalid_input`, `rejected_by_source`, `rate_limited`, `source_unavailable` or `charge_limit_reached`. The status message on the run page repeats it in a sentence. If the Hub rate limit was used up for longer than the Actor waits (100 seconds), the rows saved so far are kept and a new run a few minutes later starts with a fresh quota.

#### Why do I get a row with `recordType` set to `no_results`?

The search matched nothing. Loosen the filters or shorten the search text. Filters combine with AND, so each extra filter can only reduce the list.

#### A filter was ignored. Why?

Some filters apply to one resource type only, for example Space SDK applies to Spaces and Library applies to models. The `STATS` record lists the ignored filters in `ignoredFilters`.

#### Can I schedule it?

Yes. Use an Apify schedule with the same input, then compare runs by `id` to see which repositories are new.

If this saved you time, a rating helps others find it.

# Actor input Schema

## `resource` (type: `string`):

Choose what to list: models, datasets, Spaces or daily papers.

## `searchQuery` (type: `string`):

Type words from the repository name, for example llama or sentiment. For papers, type a topic, for example diffusion. Leave it empty to list the top results for your sort order.

## `maxItems` (type: `integer`):

Set how many rows to return, from 1 to 10,000. Each saved row is one charged result. A paper search returns up to 120 rows.

## `owner` (type: `string`):

Enter an owner namespace to list its repositories, for example meta-llama or google. Applies to models, datasets and Spaces.

## `task` (type: `string`):

Enter a task name, for example text-generation or text-classification. For models this is the pipeline tag, for datasets the task category.

## `license` (type: `string`):

Enter a license id, for example apache-2.0 or mit.

## `language` (type: `string`):

Enter a language code, for example en or de. Applies to models and datasets.

## `library` (type: `string`):

Enter a library name, for example transformers or diffusers. Applies to models.

## `spaceSdk` (type: `string`):

Choose the SDK a Space is built with. Applies to Spaces.

## `sortBy` (type: `string`):

Choose the ranking. The default is downloads for models and datasets, likes for Spaces and the Hub's newest-first order for papers. Spaces rank by likes, trending score, created or modified. Papers rank by trending score or by the Hub's newest-first order.

## `tags` (type: `array`):

Add Hub tags to narrow the list, for example task_categories:text-classification or size_categories:1M\<n<10M. Rows match all tags.

## `paperDate` (type: `string`):

Enter a day as YYYY-MM-DD to list the papers featured on that day, for example 2026-10-01. Applies to papers when the search text is empty.

## `onlyNew` (type: `boolean`):

Return only items that this monitor has not delivered before. The first run returns everything and becomes the baseline. Use it with a daily schedule.

## `monitorName` (type: `string`):

Names the memory of this monitor. Use one name per saved task, so two tasks never share their memory.

## Actor input object example

```json
{
  "resource": "models",
  "maxItems": 20,
  "task": "text-generation",
  "sortBy": "default",
  "onlyNew": false,
  "monitorName": "default"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `stats` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "resource": "models",
    "maxItems": 20,
    "task": "text-generation"
};

// Run the Actor and wait for it to finish
const run = await client.actor("conserving_celerytop/huggingface-hub-search-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "resource": "models",
    "maxItems": 20,
    "task": "text-generation",
}

# Run the Actor and wait for it to finish
run = client.actor("conserving_celerytop/huggingface-hub-search-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "resource": "models",
  "maxItems": 20,
  "task": "text-generation"
}' |
apify call conserving_celerytop/huggingface-hub-search-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,conserving_celerytop/huggingface-hub-search-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/GzhNBu7pti7K8Z1Dk/builds/zWqGvDR85vjkgWK1p/openapi.json