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.

POSThttps://rankfield.dev/v1/html/link-extraction/jobs

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/"]}'

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

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());

{
  "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"
}

{
  "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.
`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.
`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.
`resultsUrl`	string	Read pages with Get Link Extraction 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, the tool for this is start_link_extraction_job.

Start a Link Extraction job

#Parameters

#Headers

#Body

#Delivery

#Response

#Errors

#Limits

#MCP