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

# Start a Link Extraction job

> Run Link Extraction on up to 600 pages in one background job, then read each page's result as soon as it is ready.

`POST https://rankfield.dev/v1/html/link-extraction/jobs`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/html/link-extraction/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: crawl-2026-10-25' \
  -d '{"urls":["https://www.iana.org/help/example-domains","https://example.com/"]}'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/html/link-extraction/jobs",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": "crawl-2026-10-25"},
    json={"urls": ["https://www.iana.org/help/example-domains", "https://example.com/"]},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/html/link-extraction/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "crawl-2026-10-25",
  },
  body: JSON.stringify({"urls":["https://www.iana.org/help/example-domains","https://example.com/"]}),
});
console.log(await response.json());
```

```json 202
{
  "id": "01a1737c-067c-738f-a990-07518fe64d5e",
  "status": "queued",
  "total": 2,
  "view": "unique",
  "delivery": "standard",
  "createdAt": "2026-10-25T14:34:30.396Z",
  "deadlineAt": "2026-10-25T14:40:00.396Z",
  "expiresAt": "2026-10-26T14:34:30.396Z",
  "statusUrl": "/v1/html/link-extraction/jobs/01a1737c-067c-738f-a990-07518fe64d5e",
  "resultsUrl": "/v1/html/link-extraction/jobs/01a1737c-067c-738f-a990-07518fe64d5e/results"
}
```

```json 413
{
  "error": {
    "message": "A job can hold at most 600 URLs"
  }
}
```

## Parameters

### Headers

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `Authorization` | string | Yes | – | `Bearer` followed by your API key. See [Authentication](/docs/get-started/authentication). |
| `Idempotency-Key` | string | No | – | Up to 100 letters, digits, `.`, `_` or `-`. Sending the same key with the same body again returns the same job instead of a new one. |

### Body

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `urls` | string[] | Yes | – | 1–600 page URLs, with the same rules as `url` on the single-page request. |
| `view` | string | No | `unique` | `unique` or `occurrences`. Choose `occurrences` to be able to read either view later. |
| `delivery` | string | No | `standard` | `standard`: every page within 330 seconds. `priority`: within 90 seconds. See [Delivery](#delivery). |
| `maxAge` | integer | No | `60` | Seconds, 0–3,600. A page fetched at most this long ago may be reused. |

## Delivery

The deadline is fixed per job, whatever its size: `priority` 90 seconds, `standard` 330 seconds (`deadlineAt` in the answer). By then every page is answered, as a result or as failed. Pages from one website are fetched at up to 5 a second, so about 400 pages of one site fit a `priority` job and about 1,500 a `standard` one; a job spread over many sites fits easily. For many pages of one site, use `standard`.

## Response

`202` with the job:

| Field | Type | Description |
|---|---|---|
| `id` | string | The job id. |
| `status` | string | `queued` at first. |
| `total` | integer | How many URLs the job holds. |
| `delivery` | string | The deadline you chose. |
| `deadlineAt` | string | When every page should be done. |
| `expiresAt` | string | When the job and its results are deleted: 24 hours after it was created. |
| `statusUrl` | string | Follow it with [Get a Link Extraction job](/docs/link-extraction/get-a-job). |
| `resultsUrl` | string | Read pages with [Get Link Extraction results](/docs/link-extraction/get-results). |
| `replayed` | boolean | Present and `true` when this is an earlier job returned again for the same `Idempotency-Key`. |

## Errors

| Status | When |
|---|---|
| 400 | `urls` is missing or holds an invalid URL, another field is invalid, or the `Idempotency-Key` is malformed. |
| 401 | No valid API key. |
| 413 | More than 600 URLs. |
| 429 | The service is busy. Wait for `Retry-After`. |

## Limits

No per-key limits. A job holds up to 600 URLs (a single-page request is a one-URL job). When the service is busy you get `429` or `503` with `Retry-After`.

## MCP

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