SEARCH_GUIDE.md

# Hub search: URLs and Python

This guide shows how to search models using **URL parameters** and the **Python library** (`huggingface_hub`). Use it to find repos by tag, author (user or org), and more.

---

## 1. Search by URL

You can build URLs that pre-fill the Hub search.

### Main parameters

| Parameter   | Meaning                                      | Example                          |
|------------|-----------------------------------------------|----------------------------------|
| `other`    | Tags (comma-separated for multiple)          | `other=hunyuan` or `other=hunyuan,conversational` |
| `author`   | User or org that owns the repo               | `author=netflix` or `author=tencent-community`   |
| `search`   | Full-text search in repo name/description    | `search=bert`                   |

### Models

![Models search with author and keyword](image_org_keyword.png)

![Models list filtered by author and tags](image_org_tags.png)

- Base URL: `https://huggingface.co/models`
- Examples:
  - All models with tag **hunyuan**:  
    `https://huggingface.co/models?other=hunyuan`
  - Models with **two tags**:  
    `https://huggingface.co/models?other=hunyuan,conversational`
  - Models from an **org** (e.g. tencent-community):  
    `https://huggingface.co/models?author=tencent-community`
  - **Tag + author**:  
    `https://huggingface.co/models?other=hunyuan,conversational&author=tencent-community`

### Path to your model

![Full path to uploaded model](image_path_to_model.png)

---

## 2. Search with Python

The same filters are available in `huggingface_hub` via `list_models`.  
For **private** or **gated** repos, use a token (e.g. `token=True` or `token="hf_..."`).

### List models

```python
from huggingface_hub import list_models

# All models from an org (e.g. netflix – use token if private)
for repo in list_models(author="netflix", token=True):
    print(repo.id)  # e.g. netflix/mdeberta_512_v3_base, netflix/my-bert-model

# By tag
list_models(other="conversational")

# By tag + author
list_models(other="hunyuan,conversational", author="tencent-community")
```

---

## 3. Example: private org "netflix"

If your org has these models:

- **Models:** `netflix/mdeberta_512_v3_base`, `netflix/my-bert-model`

### URLs (logged in)

- All models from netflix:  
  `https://huggingface.co/models?author=netflix`

### Python (with token for private)

```python
from huggingface_hub import list_models

for m in list_models(author="netflix", token=True):
    print(m.id)
# netflix/mdeberta_512_v3_base
# netflix/my-bert-model
```

---

## 4. Discovering tags

- On a **model repo page**, the tags are listed; **clicking a tag** takes you to the models search with that tag in `other`.
- To add and manage tags on your model, see [Model cards](https://huggingface.co/docs/hub/model-cards) (metadata and tags).

---

## 5. Full reference

- **URLs:** Build `https://huggingface.co/models?other=tag1,tag2&author=<namespace>`.  
  **`author`** is the **namespace**: the org name or username (e.g. `netflix`, `tencent-community`, or a Hub username). Use the same value in URLs and in Python.
- **Python:** [Search guide](https://huggingface.co/docs/huggingface_hub/guides/search) in the docs.
- **Token:** For private/gated repos, use `token=True` (from env or cache) or `token="hf_..."` in Python; for URLs, be logged in on the site.