# arXiv Search

## Overview

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

## Description

Search arXiv papers by keyword, author query such as au:einstein, or arXiv id. A paper URL returns 400. Page through results when the match count is large.

## 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/arxiv/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### electron

```json
{
  "results": [
    {
      "doi": null,
      "url": "https://arxiv.org/abs/cond-mat/0011267v1",
      "title": "The electronic structure of cuprates from high energy spectroscopy",
      "authors": [
        {
          "name": "Mark S. Golden",
          "affiliation": null
        },
        {
          "name": "Christian Duerr",
          "affiliation": null
        },
        {
          "name": "Andreas Koitzsch",
          "affiliation": null
        },
        {
          "name": "Sibylle Legner",
          "affiliation": null
        },
        {
          "name": "Zhiwei Hu",
          "affiliation": null
        },
        {
          "name": "Sergey Borisenko",
          "affiliation": null
        },
        {
          "name": "Martin Knupfer",
          "affiliation": null
        },
        {
          "name": "Joerg Fink",
          "affiliation": null
        }
      ],
      "comment": "J. Electron Spec. Relat. Phenom.: special issue on electron correlation, in press",
      "pdf_url": "https://arxiv.org/pdf/cond-mat/0011267v1",
      "updated": "2000-11-15T16:19:15Z",
      "version": 1,
      "abstract": "We report studies of the electronic structure and elementary excitations of doped and undoped cuprate chains, ladders and planes. Using high energy spectroscopies such as x-ray absorption, core level photoemission and angle resolved photoemission spectroscopy, important information regarding the charge distribution and hole dynamics can be obtained. The comparison of the experimental data with suitable theoretical models sets constraints on the parameters entering into the model calculations, and offers insight into the important physical quantities governing the electronic structure of these materials. Recurring themes include the importance of the dimensionality of the Cu-O network (1D->2D) and the crucial role played by the spin-background in determining the dynamics of low-lying excitations in these strongly correlated systems.",
      "arxiv_id": "cond-mat/0011267",
      "published": "2000-11-15T16:19:15Z",
      "categories": [
        "cond-mat.supr-con",
        "cond-mat.str-el"
      ],
      "journal_ref": "J. Electron Spectr. Relat. Phenom. 117-118, 203 (2001)",
      "primary_category": "cond-mat.supr-con"
    }
  ],
  "pagination": {
    "next": "https://arxiv.org/search/?searchtype=all&query=electron&start=10",
    "page": 1,
    "per_page": 10,
    "total_pages": 18823,
    "total_results": 188230
  }
}
```

## Documentation

## Overview
Search arXiv papers. `query` accepts a keyword, a fielded query such as `au:einstein`, an arXiv id such as `2201.00978` or `cond-mat/0011267`, or an `https://arxiv.org/search/` URL. A paper URL (`/abs/`, `/pdf/`, or `/html/`) returns 400. Use the paper endpoint for that URL.

GET and POST take the same parameter names. Send your key in the `x-api-key` header.

## Quickstart
```
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/arxiv/search?query=electron"
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/arxiv/search?query=au:einstein"
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/arxiv/search?query=2201.00978"
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/arxiv/search?query=electron&page=2"
```

## Parameters
| Name | Detail |
|---|---|
| query | Required string. Keyword, `au:name`, arXiv id, or an arxiv.org search URL. Example: `electron`. A paper URL returns 400. |
| page | Optional integer from 1. Example: `2`. Defaults to 1. |

## Response fields
| Name | Detail |
|---|---|
| results[].arxiv_id | String. Id without the version, for example `cond-mat/0011267`. |
| results[].version | Integer or null. The `v1` suffix as a number. |
| results[].title | String. Paper title. |
| results[].authors | Array of `{name, affiliation}`. `affiliation` is null when arXiv has none. |
| results[].abstract | String or null. Summary. |
| results[].primary_category | String or null. Primary category, for example `cond-mat.supr-con`. |
| results[].categories | Array of strings. |
| results[].published | String or null. First posted time in UTC, for example `2000-11-15T16:19:15Z`. |
| results[].updated | String or null. Latest update time in UTC. |
| results[].comment | String or null. Author comment. |
| results[].journal_ref | String or null. Journal citation when the preprint was published. |
| results[].doi | String or null. |
| results[].pdf_url | String or null. PDF link. |
| results[].url | String. Abstract page, for example `https://arxiv.org/abs/cond-mat/0011267v1`. |
| pagination.page | Integer. The page you requested. |
| pagination.per_page | Integer. Always 10. |
| pagination.total_results | Integer or null. Match count. A broad keyword can be in the hundreds of thousands. |
| pagination.total_pages | Integer or null. |
| pagination.next | String or null. Next search URL, or null on the last page and when `query` is a single id. |

## Pagination
Each page returns 10 papers. For `electron`, `pagination.next` is `https://arxiv.org/search/?searchtype=all&query=electron&start=10`. Call the same endpoint with `page=2` to read the next 10. `start` in that URL is `(page - 1) * 10` for the following page. Ids on one page do not repeat, and page 2 does not repeat page 1. `next` is null only when there is no further page. An id query such as `2201.00978` returns that record and `next` is null.

## Use cases
- A lab notebook runs `au:einstein` each morning and stores new `arxiv_id` values for the paper endpoint.
- A journal club pages through `query=electron` and keeps `pdf_url` for the reading list. Totals for a keyword this broad are large, so follow `pagination.next` until it is null.
- A citation checker passes `2201.00978` and reads `journal_ref` when the preprint has a published version.

## Error codes
| Name | Detail |
|---|---|
| 400 | Missing `query`, a host other than arxiv.org, or a paper URL sent to search. |
| 404 | No matching paper. |
| 401 | Missing API key. |
| 500 | The arXiv request failed. |

## Related endpoints
- [arXiv Paper](https://www.piloterr.com/library/arxiv-paper)