# Hugging Face Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/huggingface/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/huggingface-search |

## Description

Search the public Hugging Face models API by keyword and follow pagination.next to the next cursor page.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/huggingface/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### bert-base-uncased

```json
{
  "results": [
    {
      "id": "google-bert/bert-base-uncased",
      "url": "https://huggingface.co/google-bert/bert-base-uncased",
      "tags": [
        "transformers",
        "pytorch",
        "tf",
        "jax",
        "rust",
        "coreml",
        "onnx",
        "safetensors",
        "bert",
        "fill-mask",
        "exbert",
        "en",
        "dataset:bookcorpus",
        "dataset:wikipedia",
        "arxiv:1810.04805",
        "license:apache-2.0",
        "endpoints_compatible",
        "deploy:sagemaker",
        "deploy:azure",
        "region:us"
      ],
      "likes": 3060,
      "private": false,
      "downloads": 29160167,
      "created_at": "2022-03-02T23:29:04.000Z",
      "library_name": "transformers",
      "pipeline_tag": "fill-mask",
      "trending_score": 6
    }
  ],
  "pagination": {
    "next": "https://huggingface.co/api/models?search=bert&limit=20&cursor=eyIkb3IiOlt7InRyZW5kaW5nU2NvcmUiOjEsIl9pZCI6eyIkZ3QiOiI2MjFmZmRjMDM2NDY4ZDcwOWYxNzQ1MDAifX0seyJ0cmVuZGluZ1Njb3JlIjp7IiRsdCI6MX19LHsidHJlbmRpbmdTY29yZSI6bnVsbH1dLCJzZWFyY2hTZXF1ZW5jZVRva2VuIjoiQ05DSy93RWFDU0VBQUFBQUFBRHdQeG9PV2d4aUgvM0FOa2FOY0o4WFJRQWlEbG9NWWgvOXdEWkdqWENmRjBVQSJ9",
    "page": 1,
    "per_page": 20,
    "total_pages": null,
    "total_results": null
  }
}
```

## Documentation

## Overview

Search public models through the Hugging Face models API (`huggingface.co/api/models`). This is the public catalog, not a private Hub namespace. Send a keyword such as `bert` or `llama`, a models page URL, or the full `pagination.next` URL from a previous response. The response is `{ results, pagination }`.

Model ids look like `google-bert/bert-base-uncased`. Pass `results[].id` to `/v2/huggingface/model`.

## Quickstart

GET and POST take the same `query`.

```
GET https://api.piloterr.com/v2/huggingface/search?query=bert
```

The first card for `bert` is `google-bert/bert-base-uncased`, pipeline `fill-mask`, library `transformers`. Its likes and downloads match `/v2/huggingface/model` for that id. `pagination.next` is a cursor URL on `huggingface.co/api/models`. Send that whole URL back as `query` to read the following page.

## Parameters

| Parameter | Required | Example |
|---|---|---|
| `query` | yes | `bert` |

`query` is required. A keyword becomes `search` on the models API with a page size of 20. A `https://huggingface.co/models` URL is accepted when it has `search`, `q`, or `cursor`. A `https://huggingface.co/api/models` URL, including `pagination.next`, is passed through. Any other host returns 400.

## Pagination

A keyword request sets `pagination.page` to `1`, `pagination.per_page` to the number of models returned (20 when the page is full), and `pagination.total_results` and `pagination.total_pages` to `null`. Hugging Face does not print a page count. `pagination.next` is the `rel="next"` link, or `null` when that link is absent.

Page 2 of `bert` is the `pagination.next` URL from page 1. On that call `pagination.page` is `null`, because a cursor URL has no page number. The ids on page 2 are different from page 1, and `next` is another cursor URL while further pages exist. `next` is `null` only when the models API sends no next link. Do not build a `page=2` URL yourself. Pass the cursor you received.

Ids are unique on a page. They use the `owner/name` form.

## Response fields

| Field | Type | Meaning |
|---|---|---|
| `results[].id` | string | Model id, `owner/name` |
| `results[].url` | string | Model page, `https://huggingface.co/` plus the id |
| `results[].pipeline_tag` | string or null | Task, such as `fill-mask` |
| `results[].library_name` | string or null | Library, such as `transformers` |
| `results[].likes` | number or null | Likes |
| `results[].downloads` | number or null | Downloads |
| `results[].trending_score` | number or null | Trending score |
| `results[].private` | boolean or null | Private flag |
| `results[].tags` | array | Tags from the models API |
| `results[].created_at` | string or null | Creation time |
| `pagination.page` | integer or null | `1` on a keyword search. `null` when `query` is a cursor URL |
| `pagination.per_page` | integer or null | Models on this page |
| `pagination.total_results` | null | Not provided by the models API |
| `pagination.total_pages` | null | Not provided by the models API |
| `pagination.next` | string or null | Cursor URL, or `null` on the last page |

## Use cases

- Find `google-bert/bert-base-uncased` from the keyword `bert` and keep the id for the model call.
- Follow `pagination.next` once to read the next 20 bert models, and stop when `next` is `null`.
- Sort the first page by `downloads` before choosing a fill-mask model to open.

## Error codes

| Code | Meaning |
|---|---|
| `400` | Empty query, or a URL outside huggingface.co |
| `401` | Missing API key |
| `404` | The payload was not a model list |
| `500` | The fetch failed |

## Related endpoints

[Hugging Face Model](https://www.piloterr.com/library/huggingface-model)