First request

How arXivv behaves the first time a paper is requested, and how to wait for inferred fields or build asynchronously with Prefer.

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 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

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

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

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/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.

MCP

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