---
title: First request
description: How arXivv behaves the first time a paper is requested, and how to wait for inferred fields or build asynchronously with Prefer.
sidebar:
  order: 7
---

Papers are built on demand. The first request for a version builds its tree from arXiv's HTML, stores it, then serves it. Concurrent first requests share one build.

## Default

| Step            | Time            | Result                                                                          |
| --------------- | --------------- | ------------------------------------------------------------------------------- |
| Build the tree  | ~1–3 s          | Content returned in the same response                                           |
| Inferred fields | ~5–40 s         | `inferred.status` is `pending`, with `Retry-After: 10`                          |
| Figure images   | After the build | Mirrored in the background; [asset URLs](/formats#figure-assets) 404 until then |

Later requests are served from storage and cache.

## Choosing behaviour

| Option | Header                  | Query     | Applies to                                     | Effect                                                                              |
| ------ | ----------------------- | --------- | ---------------------------------------------- | ----------------------------------------------------------------------------------- |
| Wait   | `Prefer: wait=N`        | `?wait=N` | `.json` and `outline.json` only                | Wait up to `N` seconds (max 60) for inferred fields. Returns whatever is ready then |
| Async  | `Prefer: respond-async` | `?async`  | Paper routes except assets and `metadata.json` | If the tree is not built yet, start the build and return `202 Accepted`             |

- Query parameters exist for agents that can only fetch plain URLs. They behave like the header.
- `?async` needs no value; `?async=0`, `false` or `no` turn it off.
- `N` must be a non-negative integer; larger values are capped at 60. A header value overrides the query value.
- On other routes `wait` is ignored: no `Preference-Applied`, normal caching.
- `metadata.json` ignores `Prefer` entirely. It never builds and never waits; it returns what exists now.

## Wait

```bash
curl -i -H 'Prefer: wait=30' https://arxivv.org/1706.03762.json
# or
curl -i 'https://arxivv.org/1706.03762.json?wait=30'
```

```http
HTTP/2 200
Content-Type: application/json
Preference-Applied: wait=30
Cache-Control: no-store
Vary: Prefer
X-Arxivv-Version: 7
Link: </1706.03762v7.json>; rel="canonical"
Cache-Tag: paper:1706.03762
```

The server checks `inferred` once a second until it is no longer `pending` or the wait runs out. If it is still `pending`, the response says so and adds `Retry-After: 10`.

## Async

```bash
curl -i -H 'Prefer: respond-async' https://arxivv.org/1706.03762v7.md
# or
curl -i 'https://arxivv.org/1706.03762v7.md?async'
```

When the tree is not built yet:

```http
HTTP/2 202
Content-Type: application/json
Preference-Applied: respond-async
Location: https://arxivv.org/1706.03762v7.md?async
Retry-After: 5
Cache-Control: no-store
Vary: Prefer

{"status":"building","location":"https://arxivv.org/1706.03762v7.md?async"}
```

`Location` is the requested URL itself. Poll it until it returns `200`. When the tree already exists, the content comes back immediately with `200` and no `Preference-Applied`.

## Response headers

| Header                              | When                                                                                      | Value                                   |
| ----------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------- |
| `Preference-Applied`                | `wait` on `.json`/`outline.json`, or a `202`                                              | `wait=N` (as capped) or `respond-async` |
| `Retry-After`                       | Inferred fields still `pending` (`.json`, `outline.json`)                                 | `10`                                    |
| `Retry-After`                       | `202`                                                                                     | `5`                                     |
| `Location`                          | `202`                                                                                     | The requested URL                       |
| `Cache-Control: no-store`           | A preference was applied                                                                  | These responses are never cached        |
| `Cache-Control: public, max-age=30` | Inferred fields `pending` or `failed` and no preference applied (`.json`, `outline.json`) | Short cache until ready                 |

## Failures

| Situation                         | Response           |
| --------------------------------- | ------------------ |
| arXiv has no HTML for the version | `422 no-html`      |
| arXiv errors or rate-limits us    | `502 upstream`     |
| The build fails                   | `500 build-failed` |

See [errors and limits](/errors-and-limits).

## MCP

The `outline` tool takes an equivalent `wait` argument, e.g. `outline({ paper: "1706.03762", wait: 30 })`. See [MCP server](/mcp).