# Hugging Face Scraper - Models, Datasets & Spaces API (`infinite_seascape/hf-hub-trending-scraper`) Actor

All Hugging Face Hub repo types in one run — models, datasets & Spaces with likes, downloads, trending score, license and tags. Only-new mode for schedules. $1.50 / 1,000 results.

- **URL**: https://apify.com/infinite_seascape/hf-hub-trending-scraper.md
- **Developed by:** [John Huang](https://apify.com/infinite_seascape) (community)
- **Categories:** AI, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 result 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 Hub Scraper - Models, Datasets & Spaces

Extract public metadata for **Hugging Face models, datasets and Spaces in one run** — likes, downloads, trending score, pipeline task, license, tags, created/updated dates. Built on the official Hub JSON API. No login, no browser.

**Pay-per-event pricing (when enabled by the owner):** `$1.50 / 1,000` results (`result` event) + default Actor start (`$0.00005`). Platform usage is not charged on top when PPE is configured without "+ usage".

### Why this Actor

| Capability | Included |
|---|---|
| Models + datasets + Spaces, unified schema | ✅ |
| Sort by trending / likes / downloads / date | ✅ |
| Filter by author, keyword, tags | ✅ |
| **Only-new-since-last-run** (schedule-friendly) | ✅ |
| Official Hub API, polite rate limit + 429 retry | ✅ |

### Use cases

AI trend monitoring · open-model selection · license compliance screening · newsletter / research feeds · investment research.

### Input

| Field | Description |
|---|---|
| `repoTypes` | `models`, `datasets`, `spaces` (any combination). Prefill scrapes all three. |
| `search` / `author` / `filterTags` | Optional filters (e.g. `llama`, `google`, `text-generation`, `license:apache-2.0`) |
| `sort` | `trendingScore` (default), `likes`, `downloads`, `lastModified`, `createdAt` |
| `maxItemsPerType` | Cap per type (default 50; paginates 100/page via Link header) |
| `onlyNew` | Remember seen IDs in KV store `hf-hub-state` and return only new repos |

Example:

```json
{ "repoTypes": ["models", "datasets", "spaces"], "sort": "trendingScore", "maxItemsPerType": 50 }
```

### Output

One dataset row per repo: `repoType`, `id`, `author`, `url`, `likes`, `downloads`, `trendingScore`, `pipelineTag`, `libraryName`, `sdk`, `license`, `gated`, `tags`, `createdAt`, `lastModified`, `scrapedAt`. Views: **Overview**, **Trending leaderboard**, **License screening**, **All fields**. Run counters and warnings: key-value record `RUN_STATS`. See `sample-output.json`.

### Pricing notes

- Event `result`: one Hub repo (model / dataset / Space) with public metadata — **$0.0015** each ($1.50 / 1,000).
- Event `apify-actor-start`: default start charge.
- Respects the run's **Max cost per run** — the Actor stops when the budget is reached.
- Do not enable both `result` and `apify-default-dataset-item` (would double-charge).

### Use via Apify MCP (Claude, Cursor, Windsurf, Copilot)

This Actor is a normal Store Actor with **pay-per-event** pricing, so it works with Apify's hosted MCP server and with **agentic payments** (prepaid tokens / Skyfire-style pay-per-request). Monetization stays on Apify — no Smithery listing required.

**Pin this Actor as a tool** (recommended for agents):

```text
https://mcp.apify.com?tools=infinite_seascape/hf-hub-trending-scraper
```

Or let the agent discover it with the default `search-actors` / `call-actor` tools at `https://mcp.apify.com`.

Example agent input (keep `maxItemsPerType` ≤ 20 — `call-actor` waits ~30s by default):

```json
{ "repoTypes": ["models"], "sort": "trendingScore", "maxItemsPerType": 10, "filterTags": ["text-generation"] }
```

After `call-actor` returns, read rows with `get-dataset-items` using the run's `datasetId`. Cap spend with `callOptions.maxTotalChargeUsd` (not an Actor input field).

Docs: https://docs.apify.com/mcp · Configurator: https://mcp.apify.com/

### Run locally

```
npm install
## edit storage/key_value_stores/default/INPUT.json
npm start   # or: apify run
```

### Compliance

Uses the documented public Hub API (`/api/models`, `/api/datasets`, `/api/spaces`). huggingface.co/robots.txt allows `/`. 500 ms delay between pages; retry/backoff on 429. No personal data beyond public usernames/org names. Review https://huggingface.co/terms-of-service before commercial use. Not affiliated with Hugging Face.

### Tutorial: build a daily AI trend radar from Hugging Face in 10 minutes

**Goal:** every morning, get the Hugging Face models, datasets and Spaces that started trending since yesterday — as JSON/CSV, a Google Sheet, or a Slack message.

Actor: **Hugging Face Hub Scraper - Models, Datasets & Spaces** (`infinite_seascape/hf-hub-trending-scraper`). Pricing: $1.50 per 1,000 results (+ $0.00005 per run start).

#### 1. First run: see what's trending

Input:

```json
{ "repoTypes": ["models", "datasets", "spaces"], "sort": "trendingScore", "maxItemsPerType": 20 }
```

You get 60 rows (20 per type) with `repoType`, `id`, `likes`, `downloads`, `trendingScore`, `pipelineTag`, `license`, `tags`, `lastModified`, `url`. Open the **Overview** view in the Output tab.

Cost: 60 results × $0.0015 ≈ $0.09.

#### 2. Narrow it down

- Only text-generation models with a permissive license:

```json
{ "repoTypes": ["models"], "filterTags": ["text-generation", "license:apache-2.0"], "sort": "trendingScore", "maxItemsPerType": 50 }
```

- One organisation: `"author": "google"` (a full `https://huggingface.co/google` URL also works).
- Keyword: `"search": "embedding"`. Tip: the Hub API is sometimes slow for *trending + search*; the Actor automatically retries sorted by likes and tells you in the log.

#### 3. Turn on "only new"

```json
{ "repoTypes": ["models", "datasets", "spaces"], "sort": "trendingScore", "maxItemsPerType": 50, "onlyNew": true }
```

The Actor remembers every repo it has returned (key-value store `hf-hub-state`) and on the next run outputs only repos it hasn't seen. You pay only for new results.

#### 4. Schedule it

Console → **Schedules** → *Create* → cron `0 7 * * *` (daily 07:00) → add this Actor with the input above.

#### 5. Send results somewhere

Actor → **Integrations**: Slack, Google Sheets, Zapier, Make, n8n or a webhook on *Run succeeded*. Or call the API:

```bash
curl "https://api.apify.com/v2/acts/infinite_seascape~hf-hub-trending-scraper/run-sync-get-dataset-items?token=<YOUR_TOKEN>" \
  -H 'Content-Type: application/json' -d '{"repoTypes":["models"],"maxItemsPerType":10}'
```

#### 6. Keep costs predictable

Set **Max cost per run** (e.g. $0.20). The Actor stops cleanly when the budget is reached and says so in the status message.

#### Good to know

- Data comes from the official public Hub API; no login, no private repos.
- `downloads` is the Hub's recent-downloads figure (not shown for Spaces).
- Not affiliated with Hugging Face.

# Actor input Schema

## `repoTypes` (type: `array`):

Which Hub resource types to return. Combine freely. Prefill scrapes models + datasets + spaces. Empty/default falls back to models only.

## `search` (type: `string`):

Optional Hub full-text query, e.g. "llama", "embedding", "whisper". Leave empty for pure trending/likes leaderboards. Combined with trendingScore the Hub API can be slow; the Actor may fall back to likes sort.

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

Optional Hub user or org slug, e.g. "google", "meta-llama", "openai". Also accepts a full https://huggingface.co/<author> URL.

## `filterTags` (type: `array`):

Hub tags that ALL must match, e.g. \["text-generation","license:apache-2.0"]. Useful for license screening and task filters.

## `sort` (type: `string`):

Sort key for Hub listings: trendingScore (default), likes, downloads, lastModified, createdAt.

## `maxItemsPerType` (type: `integer`):

Max rows per repo type (models/datasets/spaces). Prefill 20 keeps MCP/demo runs under 30s. Hard cap 10000; paginates 100/page.

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

If true, skip repo IDs already returned in prior runs (named KV store hf-hub-state). Ideal for daily schedules. Named store is only opened when this is true (Store QA limited permissions safe).

## Actor input object example

```json
{
  "repoTypes": [
    "models",
    "datasets",
    "spaces"
  ],
  "search": "",
  "filterTags": [],
  "sort": "trendingScore",
  "maxItemsPerType": 20,
  "onlyNew": false
}
```

# Actor output Schema

## `overview` (type: `string`):

All scraped repos; Overview view selected by default (switch to 'All fields' for every column).

## `runStats` (type: `string`):

Counters, warnings and stop reasons.

# 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 = {
    "repoTypes": [
        "models",
        "datasets",
        "spaces"
    ],
    "search": "",
    "filterTags": [],
    "maxItemsPerType": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("infinite_seascape/hf-hub-trending-scraper").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 = {
    "repoTypes": [
        "models",
        "datasets",
        "spaces",
    ],
    "search": "",
    "filterTags": [],
    "maxItemsPerType": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("infinite_seascape/hf-hub-trending-scraper").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 '{
  "repoTypes": [
    "models",
    "datasets",
    "spaces"
  ],
  "search": "",
  "filterTags": [],
  "maxItemsPerType": 20
}' |
apify call infinite_seascape/hf-hub-trending-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,infinite_seascape/hf-hub-trending-scraper"
        }
    }
}
```

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/cOOphYPVCzLgOL49T/builds/t2cOoyAsEoUpbJucc/openapi.json