# Hugging Face Models & Datasets Search (`grit-77/hf-models`) Actor

Hugging Face repository search for model and dataset discovery. Export public model, dataset and Space metadata as JSON with source links.

- **URL**: https://apify.com/grit-77/hf-models.md
- **Developed by:** [Grit](https://apify.com/grit-77) (community)
- **Categories:** AI, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 hub items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 Models & Datasets Search

Hugging Face models scraper returns public model, dataset, or Space repository metadata and source links.

Hugging Face models scraper uses the public source named below and writes its results to the Actor dataset.

Use keyword search with task, library, author, license and tag filters to prepare model shortlists, dataset inventories and lists of public demos. The actor uses the [official Hugging Face Hub API](https://huggingface.co/docs/hub/api). It retrieves repository metadata rather than model weights or dataset records.

### What it returns

Fields vary by result type and optional enrichment. The examples below are from `sample_output.json`.

| Output field | Type | Example value or excerpt from saved sample |
|---|---|---|
| `status` | string | `"ok"` |
| `type` | string | `"model"` |
| `id` | string | `"google-bert/bert-base-uncased"` |
| `url` | string | `"https://huggingface.co/google-bert/bert-base-uncased"` |
| `author` | string | `"google-bert"` |
| `downloads` | integer or null | `38734727` |
| `likes` | integer | `3386` |
| `lastModified` | string | `"2024-02-19T11:06:12.000Z"` |
| `createdAt` | string | `"2022-03-02T23:29:04.000Z"` |
| `license` | string or null | `"apache-2.0"` |
| `licenses` | array | `["apache-2.0"]` |
| `task` | string or null | `"fill-mask"` |
| `tasks` | array | `["fill-mask"]` |
| `library` | string or null | `"transformers"` |
| `libraries` | array | `["transformers"]` |
| `sdk` | string or null | `"gradio"` |
| `tags` | array | `["transformers"]` |
| `gated` | boolean or null | `false` |
| `private` | boolean | `false` |
| `sha` | string | `"86b5e0934494bd15c9632b12f734a8a67f723594"` |
| `title` | string | `"google-bert/bert-base-uncased"` |
| `description` | string or null | `"\n\t\n\t\t\n\t\tBERTIN Alpaca Spanish\n\t\n\nThis dataset is a translation to Spanish of alpaca_dat…` |
| `fetchedAt` | string | `"2026-10-05T13:18:21.941894+00:00"` |
| `errorCode` | null | `null` |
| `error` | null | `null` |

One row per repository, deduplicated by repository type and id. Missing metadata is null or an empty array.

| Field | Meaning |
|---|---|
| status | ok or error; inspect this before consuming a row |
| type | model, dataset or space |
| id, url | Public repository id and Hugging Face page URL |
| author | Published user or organization handle |
| title, description | Card title and description when published |
| downloads, likes | Counts published by the Hub; unavailable counts are null |
| lastModified, createdAt | Hub timestamps, when available |
| license, licenses | First published license and the complete license list |
| task, tasks | Model pipeline tag or dataset task categories |
| library, libraries | Published libraries; Space SDK is included here |
| sdk | Space SDK, such as gradio; null for other types |
| tags | Published Hub tags |
| gated, private | Published access flags; private repositories are excluded |
| sha | Published repository revision |
| fetchedAt | Time the actor normalized the metadata, in UTC |
| errorCode, error | Diagnostic fields; null on successful rows |

Dataset views show repository metrics and detailed tags. The RUN_SUMMARY key-value record reports saved item/error counts, the configured limits, processing time and whether charging stopped the run.

### Input example

Search model repositories with all filters applied together:

```json
{
  "query": "bert",
  "resourceTypes": ["models"],
  "task": "fill-mask",
  "library": "transformers",
  "author": "google-bert",
  "license": "apache-2.0",
  "tags": ["pytorch"],
  "minDownloads": 1,
  "minLikes": 1,
  "modifiedAfter": "2024-01-01",
  "sortBy": "likes",
  "sortDirection": "desc",
  "maxItems": 25,
  "pageSize": 50,
  "maxPagesPerType": 10,
  "concurrency": 3
}
```

For datasets, use resourceTypes: \["datasets"], query: "glue", task: "text-classification", and library: "datasets". For Spaces, use resourceTypes: \["spaces"], query: "gradio", and library: "gradio".

For a mixed search use resourceTypes: \["models", "datasets", "spaces"]. Each page round is merged in that requested type order. Sorting applies within each type; the combined output is not a global popularity ranking. For a small mixed result cap, choose a small pageSize so the first type does not consume the cap.

query searches repository names. author matches an exact public owner. tags are exact Hub tags and must all match. license matches any published license on the card. modifiedAfter is inclusive; date-only values mean midnight UTC. task filters model pipeline tags, dataset task categories and matching published Space tags. Many Spaces do not publish a task. library filters model libraries, dataset library tags and Space SDKs.

### Output example

The following projection comes from the saved sample_output.json, captured on 2026-10-05:

```json
{
  "status": "ok",
  "type": "model",
  "id": "google-bert/bert-base-uncased",
  "url": "https://huggingface.co/google-bert/bert-base-uncased",
  "author": "google-bert",
  "downloads": 38734727,
  "likes": 3386,
  "lastModified": "2024-02-19T11:06:12.000Z",
  "license": "apache-2.0",
  "task": "fill-mask",
  "library": "transformers"
}
```

The included real sample contains nine rows: three models, three datasets and three Spaces. Metadata counts can change after capture.

### Pricing

Proposed event: item at **USD 0.001 per successful repository** (USD 1.00 per 1,000). No actor start event is proposed. Error rows are uncharged. The actor requests one item charge before saving each successful row and stops when the SDK reports the event charge limit.

The observed comparator is [ParseForge's Hugging Face Model Scraper](https://apify.com/parseforge/hugging-face-model-scraper), whose result-item event was USD 0.005 on the Free tier and USD 0.00445 on Gold, Platinum and Diamond at the 2026-10-05 check. The proposal is below each observed result tier. See PRICING.md for selection, receipts and the event configuration the owner must set before publishing.

Apify platform usage is separate from this proposed result-event price. Actual Store pricing must be configured by the owner. Local runs do not prove a cloud billing transaction.

### Limits and error handling

- maxItems: 1–10,000 output rows across selected types, including error rows; default 100.
- maxPagesPerType: 1–100; default 10. pageSize: 1–100; default 50. A bounded scan can end before maxItems is reached. A scan-limit warning is logged if pagination remains.
- concurrency: 1–10 simultaneous HTTP requests; default 3. Page requests for selected types run concurrently, so selecting one type uses one request at a time.
- requestTimeoutSecs: 10–120 per attempt; default 30. Temporary network errors and HTTP 408/429/500/502/503/504 have four attempts, with exponential backoff. Retry-After is honored within a 60-second wait cap.
- Error rows describe a failed type/page, malformed item or unsafe pagination link. Other available items/types continue within maxItems. Storage and billing failures fail the run.
- No-match queries return no rows. {} browses models sorted by likes. Invalid inputs fail with a clear message.
- Missing metrics remain null. A positive minDownloads excludes Spaces without download metrics. Download sorting is rejected when Spaces are selected.
- Only public metadata is requested. No token or login is needed. Public metadata for a gated repository does not grant access to its restricted files.
- Hub throttling, metadata changes and missing licenses can affect results. Published license metadata is not a substitute for reading the repository's license terms.

### FAQ

**Why are there fewer results than the cap?** The Hub may have fewer matches, filters can exclude rows, and `maxPagesPerType` can stop a scan.

**Do I need a proxy, login, or key?** No. The actor searches public Hugging Face Hub metadata without a login or configured proxy.

**How is it priced?** The proposed pay-per-event model charges `item` for a successfully normalized model, dataset, or Space repository row. Error rows have no custom item charge.

**How are rate limits handled?** Requests use bounded concurrency and retry temporary source responses with backoff and `Retry-After` when supplied.

**How fresh are counts and metadata?** The actor reads the Hub during the run. `fetchedAt` marks collection time; downloads and likes can change later.

**Does it download model or dataset content?** No. It returns repository metadata, not weights or dataset examples.

### Use with AI agents / MCP

After the owner publishes the actor, add its Store id to the [Apify MCP server](https://docs.apify.com/integrations/mcp) or call it through an Apify integration in your agent. Give the agent the input object above, set maxItems and a run charge limit, and have it read the returned default dataset.

Suggested agent instruction: “Search public Hugging Face models for bert with task fill-mask and library transformers. Return at most 25 repositories with URL, license, downloads and likes. Explain missing metadata and keep error rows separate.”

An agent can also send the same JSON input through the [Apify API](https://docs.apify.com/api/v2/actor-run-sync-get-dataset-items-post). Use the actual published actor id in your integration. No published actor id is supplied with this local build.

### Local development

Use the existing project venv. Do not install packages into it. Runtime dependencies are pinned in requirements.txt.

PowerShell, from this actor directory:

```powershell
$env:APIFY_LOCAL_STORAGE_DIR = "$PWD/storage"
$env:CRAWLEE_STORAGE_DIR = "$PWD/storage"
$env:NO_PROXY = "huggingface.co"
New-Item -ItemType Directory -Force storage/key_value_stores/default | Out-Null
'{"query":"bert","maxItems":5}' | Set-Content -Encoding ascii storage/key_value_stores/default/INPUT.json
& C:/GritWork/earn/.venv/Scripts/python.exe -m src
& C:/GritWork/earn/.venv/Scripts/python.exe -m pytest tests -m "not live" -q -p no:cacheprovider
& C:/GritWork/earn/.venv/Scripts/python.exe -m pytest tests -m live -q -p no:cacheprovider
apify validate-schema
```

The verification environment inherited non-working proxy settings for Python. Recorded live tests used an isolated environment without those proxy variables; production code honors the environment's proxy configuration.

Local datasets are under storage/datasets/default. Use fresh local storage for each independent sample; SDK storage can retain rows between runs. The Dockerfile uses apify/actor-python:3.12. Docker execution and real cloud billing were not tested in this local delivery.

# Actor input Schema

## `query` (type: `string`):

Keyword contained in repository names. Leave empty to browse by sort order.

## `resourceTypes` (type: `array`):

Choose any of models, datasets, spaces. Results are merged in this type order per page round.

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

Model pipeline tag or dataset task category, e.g. fill-mask or text-classification. Spaces must publish a matching task or tag.

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

Model library (transformers), dataset library (datasets, pandas), or Space SDK (gradio, streamlit).

## `author` (type: `string`):

Exact public repository owner, e.g. google-bert.

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

Exact published license identifier, e.g. apache-2.0 or mit. Matches any published license for multi-license cards.

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

Exact Hub tags; all must match. At most 20 tags.

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

Hub sort order within each repository type. Downloads cannot be used when Spaces are selected.

## `sortDirection` (type: `string`):

Descending returns highest or newest values first.

## `modifiedAfter` (type: `string`):

Inclusive ISO date or date-time, e.g. 2024-01-01 or 2024-01-01T00:00:00Z. Date-only values use UTC.

## `minDownloads` (type: `integer`):

Inclusive minimum published download count. A positive value excludes Spaces and repositories without a download count.

## `minLikes` (type: `integer`):

Inclusive minimum number of likes; a positive value excludes repositories without a published count.

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

Global cap across all types, including uncharged error rows.

## `maxPagesPerType` (type: `integer`):

Bounded scan budget; restrictive filters may return fewer than maxItems. A warning is logged when the scan limit is reached.

## `pageSize` (type: `integer`):

Requested Hub page size. A smaller page helps spread a mixed search across all selected types.

## `concurrency` (type: `integer`):

Caps simultaneous Hub HTTP requests across selected types.

## `requestTimeoutSecs` (type: `integer`):

Time limit per HTTP request. Temporary failures have at most four attempts with backoff.

## Actor input object example

```json
{
  "query": "bert",
  "resourceTypes": [
    "models"
  ],
  "tags": [],
  "sortBy": "likes",
  "sortDirection": "desc",
  "minDownloads": 0,
  "minLikes": 0,
  "maxItems": 100,
  "maxPagesPerType": 10,
  "pageSize": 50,
  "concurrency": 3,
  "requestTimeoutSecs": 30
}
```

# Actor output Schema

## `dataset` (type: `string`):

Repository metadata and any uncharged error rows.

# 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 = {
    "query": "bert"
};

// Run the Actor and wait for it to finish
const run = await client.actor("grit-77/hf-models").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 = { "query": "bert" }

# Run the Actor and wait for it to finish
run = client.actor("grit-77/hf-models").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 '{
  "query": "bert"
}' |
apify call grit-77/hf-models --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,grit-77/hf-models"
        }
    }
}
```

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/NUNMJBYIGbfYO57DQ/builds/18L7F43p2UGI3r7Tv/openapi.json