# Hugging Face Scraper: Models, Datasets & Spaces (`winterlock/huggingface-scraper`) Actor

Export Hugging Face Hub models, datasets and Spaces with downloads, likes, trending score, licence, base model and task tags parsed into their own fields. Official Hub API, no login needed for public repos.

- **URL**: https://apify.com/winterlock/huggingface-scraper.md
- **Developed by:** [Alex Burton](https://apify.com/winterlock) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 repository from a browse or searches

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 Scraper: Models, Datasets & Spaces

Export Hugging Face Hub data to JSON, CSV or Excel. Everything comes from the official Hub API — the same JSON the website itself calls — so there is no HTML parsing and no login for public repositories.

One Actor, four jobs:

| Mode | What you get |
|---|---|
| **Models** | Browse or search models with downloads, likes, trending score, task, library, licence, base model, languages and dates |
| **Datasets** | The same for datasets, plus description, task categories, size category and file formats |
| **Spaces** | The same for Spaces, plus SDK, title, short description and the models a Space runs on |
| **Specific repositories** | The full record for a list of repositories you name, including parameter count, storage size, model type and the Spaces using a model |

### Why use this one

- **The Hub hides half its metadata inside tags.** Licence, language, base model, arXiv paper, training dataset, task category and size category all arrive as namespaced strings in one `tags` array. This Actor splits them into `license`, `languages`, `baseModel`, `arxivIds`, `datasetsUsed`, `taskCategories` and `sizeCategory`, so a spreadsheet can sort and filter on them.
- **Parameter counts as a number.** `parameterCount` comes from the repository's safetensors index, so you can filter for models that will actually fit on your GPU instead of guessing from the name.
- **Base model lineage.** `baseModel` tells you what a fine-tune was built on — the quickest way to find every derivative of a given model.
- **Real pagination.** The Hub pages its list endpoints with a cursor in the `Link` header. This Actor follows it, so a request for 2,000 models returns 2,000 rows rather than the first 100.
- **No token needed.** Public models, datasets and Spaces are readable anonymously.

### How to use it

1. Choose **What to scrape**.
2. For browsing, set any of **Search terms**, **Authors or organisations** and **Filter tag**, then pick a sort order.
3. For **Specific repositories**, list them as `owner/name` and set **Repository type**.
4. Click **Start**, then download the results or pull them through the Apify API.

#### Example input: the most downloaded text-generation models

```json
{
  "mode": "models",
  "filterTag": "text-generation",
  "sortBy": "downloads",
  "maxResults": 500
}
```

#### Example input: everything an organisation publishes

```json
{
  "mode": "models",
  "authors": ["meta-llama", "mistralai", "Qwen"],
  "sortBy": "lastModified",
  "maxResults": 200
}
```

#### Example input: trending Spaces this week

```json
{
  "mode": "spaces",
  "sortBy": "trendingScore",
  "maxResults": 100
}
```

#### Example input: a watchlist of specific models

```json
{
  "mode": "repoDetails",
  "repoType": "models",
  "repositories": [
    "openai-community/gpt2",
    "meta-llama/Llama-3.1-8B-Instruct",
    "https://huggingface.co/BAAI/bge-m3"
  ]
}
```

### Output

Each item carries a `type` field: `model`, `dataset` or `space`.

**Model**

```json
{
  "type": "model",
  "hub": "huggingface",
  "repoId": "openai-community/gpt2",
  "name": "gpt2",
  "author": "openai-community",
  "pipelineTag": "text-generation",
  "libraryName": "transformers",
  "downloads": 15870518,
  "likes": 4248,
  "license": "mit",
  "languages": ["en"],
  "baseModel": null,
  "parameterCount": 137022720,
  "modelType": "gpt2",
  "fileCount": 32,
  "tags": ["transformers", "pytorch", "safetensors", "gpt2"],
  "createdAt": "2022-03-02T23:29:04Z",
  "lastModified": "2024-02-19T10:57:45Z",
  "url": "https://huggingface.co/openai-community/gpt2"
}
```

**Space**

```json
{
  "type": "space",
  "hub": "huggingface",
  "repoId": "gradio/hello_world",
  "author": "gradio",
  "sdk": "gradio",
  "title": "Hello World",
  "likes": 112,
  "runtimeStage": "RUNNING",
  "hardware": "cpu-basic",
  "models": [],
  "appUrl": "https://gradio-hello-world.hf.space",
  "url": "https://huggingface.co/spaces/gradio/hello_world"
}
```

### Pricing

Pay only for results:

| Result | Price |
|---|---|
| Repository from a browse or search | $3.00 per 1,000 |
| Repository from **Specific repositories** | $5.00 per 1,000 |

Set a maximum spend per run in the run options and the Actor stops cleanly when it is reached.

### Limits to know about

These come from the Hub API, not from this Actor:

- **`trendingScore` is only on list results.** The single-repository endpoint does not return it, so rows from **Specific repositories** have `trendingScore: null`. Sort by *Trending* in a browse mode to get it.
- **`runtimeStage` and `hardware` are only on the single-Space endpoint.** Rows from **Spaces** browsing leave them null; use **Specific repositories** with *Spaces* for live status.
- **`downloads` counts the last 30 days**, which is what the Hub publishes. There is no all-time figure in the API.
- **Spaces have no download count.** Likes and trending score are the only popularity signals the Hub exposes for them.
- **`parameterCount` needs safetensors.** Repositories published only as GGUF, PyTorch `.bin` or ONNX leave it null — nothing is inferred from the model name.
- **Gated and private repositories need a token.** Without one they are skipped and the reason is logged. Browsing never lists private repositories at all.
- **One tag per filter.** The Hub's `filter` parameter takes a single tag; run the Actor twice to intersect two of them.

### Optional Hugging Face token

Leave **Hugging Face token** empty and the Actor reads public data anonymously, which is what most runs need. Adding a free read token from [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) does two things: it raises your rate limit on big crawls, and it lets the Actor read gated repositories that your account has already been granted access to.

The token field is encrypted by Apify, is sent only to `huggingface.co`, and is never written to the dataset or the log. A read-only token is enough — never paste a write token.

### FAQ

**Do I need a Hugging Face account?** No, not for public repositories.

**Can this download model weights?** No. It exports metadata about repositories, not their files.

**How do I find every fine-tune of a model?** Browse models with the filter tag `base_model:<owner>/<name>`, then sort by downloads.

**Why do fewer rows come back than I asked for?** The Hub has run out of matches for that filter — check the log, which prints the count per search.

**Can I track releases daily?** Yes. Sort by *Recently updated* or *Newest*, create a schedule in Apify Console, and connect the dataset to Slack, Google Sheets, Zapier or Make.

### Feedback

Found a bug or need a field that is missing? Open an issue on the Actor's **Issues** tab.

# Actor input Schema

## `mode` (type: `string`):

Browse models, datasets or Spaces, or pull the full record for specific repositories.

## `searchTerms` (type: `array`):

Free-text search over repository names. Leave empty to list everything sorted by the field below.

## `authors` (type: `array`):

Limit results to these owners, for example meta-llama, google, openai-community.

## `filterTag` (type: `string`):

A single Hub tag, for example text-generation, pytorch, license:mit or en.

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

For Models, Datasets and Spaces. How the Hub orders the listing before the cap is applied.

## `maxResults` (type: `integer`):

Counted per combination of author and search term.

## `repositories` (type: `array`):

For Specific repositories. Use owner/name (openai-community/gpt2) or a huggingface.co link.

## `repoType` (type: `string`):

Which kind of repository the list above refers to.

## `hfToken` (type: `string`):

Not needed for public repositories. A free read token raises the rate limit and lets the Actor read gated repositories you have been granted access to. Create one at huggingface.co/settings/tokens. Stored encrypted, never written to the dataset.

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

Stop the run after saving this many items. Leave empty for no limit.

## `maxConcurrency` (type: `integer`):

How many requests run at once. The Hub API is generous; raise it for large detail runs.

## `proxyConfiguration` (type: `object`):

Not needed for most runs. Consider it for very large crawls.

## Actor input object example

```json
{
  "mode": "models",
  "sortBy": "downloads",
  "maxResults": 100,
  "repositories": [
    "openai-community/gpt2"
  ],
  "repoType": "models",
  "maxConcurrency": 4,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (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 = {
    "repositories": [
        "openai-community/gpt2"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("winterlock/huggingface-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 = { "repositories": ["openai-community/gpt2"] }

# Run the Actor and wait for it to finish
run = client.actor("winterlock/huggingface-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 '{
  "repositories": [
    "openai-community/gpt2"
  ]
}' |
apify call winterlock/huggingface-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,winterlock/huggingface-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/AblkCpXu1pwehyTFz/builds/d1gsSC1f0y9NCccVh/openapi.json