# huggingface.papers_search

**stable** **Advanced**

Search Hugging Face Papers.

`GET /v1/huggingface/papers_search`

## What you get

A list of Huggingface results in Onekey's unified shape, in `data` (an array). An empty array is a normal, successful answer and is charged like any other; a source that reports "nothing found" as an error returns a free `404 not_found` instead.

## What it costs

- **Advanced · 5 credits** for a fresh fetch, charged only when it succeeds.
- **Free when served from cache (0.2 credit for a cached response over 100 KB).**
- **Free** if the request is invalid (never charged) or the source fails or reports not found (refunded).

## Parameters

| Name | Type | Required | Default | What it is | Constraints |
| --- | --- | --- | --- | --- | --- |
| `q` | string | yes | (required) | Search query | max 200 chars; trimmed, repeated spaces collapsed |

## Request

```bash
curl "https://api.onekey.dev/v1/huggingface/papers_search?q=attention" \
  -H "x-api-key: YOUR_API_KEY"
```

```python
import requests

res = requests.get(
    "https://api.onekey.dev/v1/huggingface/papers_search",
    params={"q": "attention"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
body = res.json()

if body["success"]:
    print(body["data"])
else:
    print(body["error"]["code"], body["error"]["message"])
```

```javascript
const params = new URLSearchParams({ q: "attention" });
const res = await fetch(`https://api.onekey.dev/v1/huggingface/papers_search?${params}`, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const body = await res.json();

if (body.success) console.log(body.data);
else console.error(body.error.code, body.error.message);
```

## Recorded response

A real Huggingface response, recorded and returned in Onekey's shape. Fields the platform does not provide are `null`.

```json
{
  "success": true,
  "data": [
    {
      "content": {
        "id": "1706.03762",
        "title": "Attention Is All You Need",
        "text": "The dominant sequence transduction models are based on complex recurrent or\nconvolutional neural networks in an encoder-decoder configuration. The best\nperforming models also connect the encoder and decoder through an attention\nmechanism. We propose a new simple network architecture, the Transformer, based\nsolely on attention mechanisms, dispensing with recurrence and convolutions\nentirely. Experiments on two machine translation tasks show these models to be\nsuperior in quality while being more parallelizable and requiring significantly\nless time to train. Our model achieves 28.4 BLEU on the WMT 2014\nEnglish-to-German translation task, improving over the existing best results,\nincluding ensembles by over 2 BLEU. On the WMT 2014 English-to-French\ntranslation task, our model establishes a new single-model state-of-the-art\nBLEU score of 41.8 after training for 3.5 days on eight GPUs, a small fraction\nof the training costs of the best models from the literature. We show that the\nTransformer generalizes well to other tasks by applying it successfully to\nEnglish constituency parsing both with large and limited training data.",
        "createdAt": "2017-06-12T13:57:34Z"
      },
      "engagement": {
        "likes": 143,
        "comments": 14
      },
      "media": {
        "thumbnailUrl": "https://cdn-thumbnails.huggingface.co/social-thumbnails/papers/1706.03762.png"
      }
    },
    {
      "content": {
        "id": "2108.12409",
        "title": "Train Short, Test Long: Attention with Linear Biases Enables Input\n  Length Extrapolation",
        "text": "Since the introduction of the transformer model by Vaswani et al. (2017), a\nfundamental question has yet to be answered: how does a model achieve\nextrapolation at inference time for sequences that are longer than it saw\nduring training? We first show that extrapolation can be enabled by simply\nchanging the position representation method, though we find that current\nmethods do not allow for efficient extrapolation. We therefore introduce a\nsimpler and more efficient position method, Attention with Linear Biases\n(ALiBi). ALiBi does not add positional embeddings to word embeddings; instead,\nit biases query-key attention scores with a penalty that is proportional to\ntheir distance. We show that this method trains a 1.3 billion parameter model\non input sequences of length 1024 that extrapolates to input sequences of\nlength 2048, achieving the same perplexity as a sinusoidal position embedding\nmodel trained on inputs of length 2048 but training 11% faster and using 11%\nless memory. ALiBi's inductive bias towards recency also leads it to outperform\nmultiple strong position methods on the WikiText-103 benchmark.",
        "createdAt": "2021-08-27T13:35:06Z"
      },
      "engagement": {
        "likes": 5,
        "comments": 0
      },
      "media": {
        "thumbnailUrl": "https://cdn-thumbnails.huggingface.co/social-thumbnails/papers/2108.12409.png"
      }
    }
  ],
  "metadata": {
    "platform": "huggingface",
    "endpoint": "papers_search",
    "cached": false,
    "stale": false,
    "age_s": 0,
    "fetched_at": "2026-01-01T12:00:00+00:00",
    "credits_charged": 5,
    "request_id": "7f3a9c2e5b1d4c8fa2e6d0b9c4f18e37"
  },
  "error": null
}
```

## Field mapping

How this endpoint's source fields become Onekey's [unified schema](https://onekey.dev/docs/schema.md). Fields the source lacks come back as `null`.

| Source path | Onekey field | Transform |
| --- | --- | --- |
| `paper.id` | `content.id` | - |
| `title` | `content.title` | - |
| `summary` | `content.text` | - |
| `publishedAt` | `content.createdAt` | `toIsoDate` |
| `paper.upvotes` | `engagement.likes` | `toNumber` |
| `numComments` | `engagement.comments` | `toNumber` |
| `thumbnail` | `media.thumbnailUrl` | `safeUrl` |

## Caching and freshness

- Fresh for about 2 minutes. Repeat calls in that window are served from cache and are free.
- Between 2 minutes and 15 minutes the cached copy is still served instantly and marked `stale: true` while Onekey refreshes it in the background.
- If the source is down when a refresh is needed, the last copy can be served for up to 1 hour more (marked stale).
- A "not found" is remembered for 1 minute and is free.
- The cache is shared across all customers, which is what keeps repeat calls cheap.

## What can go wrong

| Status | Code | What to do |
| --- | --- | --- |
| 401 | `unauthorized` | Check the `x-api-key` header. |
| 402 | `insufficient_credits` | [Add credits](https://onekey.dev/pricing); your balance must cover the price. |
| 404 | `not_found` | Unknown endpoint path. |
| 422 | `invalid_params` | Fix the parameters using the table above. Free. |
| 429 | `rate_limited` | Wait `Retry-After` seconds, then retry. |
| 502 | `upstream_error` | The source failed. Refunded; retry with backoff. |

See [Errors](https://onekey.dev/docs/errors.md) for the full list and retry guidance.

Status: stable (verified against the live source).