# Retrieving results

Every request is assigned a token. Use it to fetch the result later with a single GET — handy for async jobs, and for sync requests that timed out before the work finished.

## When to use it

- In [async mode](https://urlpipe.dev/docs/async), as a pull alternative to (or backup for) the webhook — poll until the result is ready. An async request needs no `report_to` at all if this is how you collect results.
- After a sync request times out. A slow sync call returns `504` with the `token`, and the analysis keeps running in the background — retrieve it here once it's done.

GET/result/:token

## Fetch a result

### Path parameter

- **Name**
  : `token`
  **Type**
  : string
  **Required**
  : Required
  **Description**
  : The token identifying the original request. Requests are scoped to your project, so a token from another project returns `404`.

### Where the token comes from

- Every response carries it in the `X-Result-Token` header — sync or async, cache hit or miss. See [Response headers](https://urlpipe.dev/docs/response-headers).
- Async requests also repeat it in the response body (`token`), as does the body of a `504` timeout.

```
curl https://urlpipe.dev/result/YOUR_TOKEN \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Responses

The status code tells you whether the result is ready, still running, failed, or expired. On `200` the body is exactly what the original endpoint returns.

Every one of these responses except the `404` also carries the usual [metadata headers](https://urlpipe.dev/docs/response-headers) — the cache verdict, the processing time and your remaining quota — describing the original request, not this retrieval.

Status

When

Body

`200 OK`

The result is ready.

The result itself, in the operation's format (text or JSON) — identical to the sync response.

`202 Accepted`

Still being generated.

{ "status": "processing", "token": "…", "labels": {} } — poll again shortly.

`422 Unprocessable Entity`

The analysis ran but failed.

{ "error": "<message>" } — the same failure you'd get synchronously.

`404 Not Found`

No result for this token under your project.

{ "error": "not\_found" }

`410 Gone`

The result is older than the 30-day window.

{ "error": "stale" } — run a new analysis.

`401 Unauthorized`

Missing or invalid API key.

{ "error": "invalid\_api\_key", "message": "…" }

Poll on `202`: wait a second or two between calls. Most analyses finish within seconds — see typical times on [Async & sync modes](https://urlpipe.dev/docs/async).

## Retention & staleness

Results are retrievable for up to **30 days** — the maximum [cache](https://urlpipe.dev/docs/caching) window. After that, `GET /result/:token` returns `410 Gone` with `{ "error": "stale" }`, and you must run a new analysis to get a fresh result.

410 Gone

```
{
  "error": "stale",
  "message": "This result is older than the 30-day retention window. Run a new analysis."
}
```

Source: https://urlpipe.dev/docs/results