> ## Documentation index
> Fetch the complete documentation index at: https://rankfield.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Link Extraction results

> Read a Link Extraction job's pages as each one finishes, page through them with a cursor, or download the finished job as JSONL or CSV.

`GET https://rankfield.dev/v1/html/link-extraction/jobs/{id}/results`

```bash cURL
curl 'https://rankfield.dev/v1/html/link-extraction/jobs/01a1737c-067c-738f-a990-07518fe64d5e/results?cursor=0&wait=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/html/link-extraction/jobs/01a1737c-067c-738f-a990-07518fe64d5e/results?cursor=0&wait=20",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/html/link-extraction/jobs/01a1737c-067c-738f-a990-07518fe64d5e/results?cursor=0&wait=20", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "id": "01a1737c-067c-738f-a990-07518fe64d5e",
  "status": "running",
  "view": "unique",
  "pages": [
    {
      "position": 0,
      "url": "https://www.iana.org/help/example-domains",
      "ok": true,
      "finalUrl": "https://www.iana.org/help/example-domains",
      "status": 200,
      "title": "Example Domains",
      "redirects": [],
      "collectedAt": "2026-10-25T14:34:22.639Z",
      "cached": true,
      "counts": { "links": 26, "internal": 22, "external": 4, "occurrences": 31 },
      "links": [
        { "href": "https://www.iana.org/", "anchor": "Homepage", "internal": true, "rel": [], "nofollow": false, "sponsored": false, "ugc": false, "occurrences": 1 }
      ]
    }
  ],
  "nextCursor": 1
}
```

## Parameters

### Headers

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `Authorization` | string | Yes | – | `Bearer` followed by your API key. See [Authentication](/docs/get-started/authentication). |

### Path parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `id` | string | Yes | – | The job id. |

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `cursor` | integer | No | `0` | Where to continue: the `nextCursor` of the previous answer. |
| `limit` | integer | No | `10` | Pages per answer, 1–100. |
| `wait` | integer | No | `0` | Seconds, 0–25, to hold the request until the next page is ready. |
| `view` | string | No | `the job's view` | `unique` or `occurrences`. A job started with `occurrences` can be read either way. |
| `type` | string | No | `all` | `all`, `internal` or `external`. |
| `format` | string | No | `json` | `json` pages through results. Once the job is `completed`, `jsonl` streams one page per line and `csv` streams one row per link: `page_url, page_status, final_url, href, anchor, internal, rel, nofollow, sponsored, ugc, occurrences, error`. |

## Read pages as they finish

1. Start with `cursor=0`.
2. Each answer's `pages` holds the pages finished since your cursor, in the order they finished. `position` is the page's index in your `urls`, from 0.
3. Pass `nextCursor` back as `cursor`. When `nextCursor` is `null`, every page has been delivered and `status` is `completed`.
4. An empty `pages` list means nothing new yet: ask again after `retryAfterMs`, or add `wait=20` so the request waits for the next page.

A page that failed has `"ok": false`, its `status` and an `error` with `message`, `code` and `retryable`, as in the single-page `422`.

## Download a finished job

`?format=jsonl` streams one page per line; `?format=csv` streams one row per link: `page_url, page_status, final_url, href, anchor, internal, rel, nofollow, sponsored, ugc, occurrences, error`. Both answer `409` until the job is `completed`. A download always starts at the beginning: sending a `cursor` with it answers `400`.

## Errors

| Status | When |
|---|---|
| 400 | `cursor`, `limit`, `wait` or `format` is invalid, or a download was sent with a `cursor`. |
| 401 | No valid API key. |
| 404 | No job with this id for this key. |
| 409 | `format=jsonl` or `csv` before the job is `completed`. |
| 410 | The job has expired: jobs are kept for 24 hours after they are created. |

## MCP

On the [MCP server](/docs/agents/mcp-server), the tool for this is `get_link_extraction_results`.