# Rankfield API docs
Source: https://rankfield.dev/docs

Call Rankfield's SEO and web data API: Site Strength, referring domains, search suggestions and live page data, with one API key.

## Make your first request

1. Copy a key from the [API key panel](/?tab=key#playground). No sign-up.
2. Send it as a bearer token:

```bash
curl https://rankfield.dev/v1/domains/wikipedia.org/site-strength \
  -H "Authorization: Bearer $RANKFIELD_API_KEY"
```

3. Read the JSON: `{"domain": "wikipedia.org", "siteStrength": 100}`.

The [Quickstart](/docs/get-started/quickstart) has the same in Python and JavaScript.

## Endpoints

| Endpoint | What you get | Request |
|---|---|---|
| [Site Strength](/docs/site-strength/get-site-strength) | A domain's 0–100 link authority score | `GET /v1/domains/{domain}/site-strength` |
| [Referring Domains](/docs/referring-domains/get-referring-domains) | How many domains link to a site, and the strongest 20 | `GET /v1/domains/{domain}/referring-domains` |
| [All Referring Domains](/docs/referring-domains/list-referrers) | Every linking domain, paged or as CSV | `GET /v1/domains/{domain}/referrers` |
| [Link Extraction](/docs/link-extraction/extract-links) | Every link on a live page, with anchor text and rel | `GET /v1/html/link-extraction?url=` |
| [Scrape](/docs/scrape/scrape-a-page) | A page as Markdown, with metadata, links and structured data | `GET /v1/scrape?url=` |
| [Bot View](/docs/bot-view/check-a-page) | Which of 274 crawlers and AI bots may read a page | `GET /v1/bot-view?url=` |
| [Brand](/docs/brand/get-a-brand) | A company's logos, colours, fonts and profiles | `GET /v1/brand?domain=` |
| [Site Map](/docs/map/map-a-site) | Every URL of a website | `GET /v1/map?domain=` |
| [Site Audit](/docs/site-audit/audit-a-website) | Every page of a website checked for technical SEO and AEO problems | `POST /v1/site-audit` |
| [Bing Suggest](/docs/suggest/get-bing-suggestions) | Bing autocomplete for a keyword | `GET /v1/bing/suggest?query=` |
| [DuckDuckGo Suggest](/docs/suggest/get-duckduckgo-suggestions) | DuckDuckGo autocomplete for a keyword | `GET /v1/ddg/suggest?query=` |
| [Yahoo Search Predictions](/docs/suggest/get-yahoo-search-predictions) | Yahoo's predictions for a keyword | `GET /v1/yahoo/search-predictions?query=` |

Every endpoint takes the same key. For many URLs, domains or keywords at once, each one also has [batch jobs](/docs/get-started/batch-jobs).

## Before you build

- [Authentication](/docs/get-started/authentication): Send the key, get one from code, and keep it safe.
- [Errors](/docs/get-started/errors): Status codes, error bodies and which errors to retry.
- [Rate limits](/docs/get-started/rate-limits): How much one request or job holds, and what to do about a 429.
- [Batch jobs](/docs/get-started/batch-jobs): Start a job, follow it, and read results as they finish.

## For AI agents

- [For coding agents](/docs/agents/for-coding-agents): The whole API on one page: auth, which endpoint to pick, timeouts and gotchas.
- [MCP server](/docs/agents/mcp-server): Connect Claude, Cursor or any MCP client with your key.
- [Agent skill](/docs/agents/agent-skill): One SKILL.md file that teaches an agent to use Rankfield.
- [llms.txt and Markdown pages](/docs/agents/llms-txt-and-markdown): Every page as Markdown, indexed in /llms.txt.
:::


---

# Get started
Source: https://rankfield.dev/docs/get-started

Get a Rankfield API key, make your first request, and learn how keys, errors, rate limits and batch jobs work.

Every Rankfield endpoint takes the same API key in the same header, answers in JSON, and returns errors with an HTTP status you can act on. Read these pages once; the endpoint pages then only describe what differs.

## Pages

- [Quickstart](/docs/get-started/quickstart): Get an API key, make your first Rankfield request with cURL, Python or JavaScript, and read the answer.
- [Authentication](/docs/get-started/authentication): Authenticate every Rankfield API request with your API key in the Authorization header, and keep the key safe.
- [Errors](/docs/get-started/errors): Read Rankfield API errors: the HTTP status codes, the JSON error body of each endpoint family, and which errors to retry.
- [Rate limits](/docs/get-started/rate-limits): See how much one Rankfield request or job can hold, what a busy server answers, and how to avoid 429 errors.
- [Batch jobs](/docs/get-started/batch-jobs): Send many URLs, domains or keywords in one Rankfield batch job, follow its progress, and read results as they finish.
:::


---

# Quickstart
Source: https://rankfield.dev/docs/get-started/quickstart

Get an API key, make your first Rankfield request with cURL, Python or JavaScript, and read the answer.

## 1. Get an API key

Open the [API key panel](/?tab=key#playground) and click **Copy**. There is no sign-up, no card and no expiry date. Keys start with `ls_`.

Keep the key in an environment variable rather than in your code:

```bash
export RANKFIELD_API_KEY="ls_..."
```

An AI agent can get its own key with one request:

```bash
curl -sS -X POST https://rankfield.dev/v1/keys -H 'Origin: https://rankfield.dev'
```

The answer's `key` field holds the key.

## 2. Make your first request

Ask for the Site Strength of a domain. Send the key as a bearer token:

```bash cURL
curl https://rankfield.dev/v1/domains/wikipedia.org/site-strength \
  -H "Authorization: Bearer $RANKFIELD_API_KEY"
```

```python Python
import os, requests

response = requests.get(
    "https://rankfield.dev/v1/domains/wikipedia.org/site-strength",
    headers={"Authorization": f"Bearer {os.environ['RANKFIELD_API_KEY']}"},
)
response.raise_for_status()
print(response.json()["siteStrength"])
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/domains/wikipedia.org/site-strength", {
  headers: { Authorization: `Bearer ${process.env.RANKFIELD_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
console.log((await response.json()).siteStrength);
```

## 3. Read the answer

```json 200
{
  "domain": "wikipedia.org",
  "siteStrength": 100
}
```

`siteStrength` is a 0–100 score from the Rankfield web graph; [How Site Strength works](/docs/site-strength/how-site-strength-works) explains it. Any other status is an error with a JSON body: see [Errors](/docs/get-started/errors).

The API does not send CORS headers. Call it from a server, a script or an agent, not from browser JavaScript on another site.

## Next steps

- Pick an endpoint from the [docs overview](/docs).
- Many URLs or keywords at once: [Batch jobs](/docs/get-started/batch-jobs).
- Connect an AI agent: [MCP server](/docs/agents/mcp-server) or [Agent skill](/docs/agents/agent-skill).


---

# Authentication
Source: https://rankfield.dev/docs/get-started/authentication

Authenticate every Rankfield API request with your API key in the Authorization header, and keep the key safe.

## Send the key

Every endpoint under `https://rankfield.dev/v1/` and the [MCP server](/docs/agents/mcp-server) need the key in the `Authorization` header:

```http
Authorization: Bearer ls_your_key
```

The same key works for every endpoint. Get one from the [API key panel](/?tab=key#playground). Keys do not expire.

## When the key is missing or wrong

The answer is `401` with a `WWW-Authenticate: Bearer` header. Check that the header reads exactly `Bearer ` followed by the key, with no quotes or line break.

```json 401
{
  "error": {
    "message": "A valid API key is required"
  }
}
```

## Get a key from code

Agents and scripts can ask for a key without a browser:

```bash
curl -sS -X POST https://rankfield.dev/v1/keys -H 'Origin: https://rankfield.dev'
```

The `Origin` header is required. Reuse one key rather than asking for a new one per run. When key issuance is at capacity, the answer is `429`; try again later.

## Keep your key safe

- Load it from an environment variable or a secret store. Never commit it, paste it in an issue, or put it in a screenshot or log.
- Send it only in the `Authorization` header over HTTPS. Never put it in a URL, where it ends up in logs and browser history.
- Keep it on your server. Browser JavaScript and mobile apps would expose it, and the API does not send CORS headers anyway.
- An agent should never print the key in its answer.


---

# Errors
Source: https://rankfield.dev/docs/get-started/errors

Read Rankfield API errors: the HTTP status codes, the JSON error body of each endpoint family, and which errors to retry.

## Status codes

| Status | Meaning | What to do |
|---|---|---|
| `200` | Success. | Read the JSON. |
| `202` | Accepted: a job started, or a page is still being fetched. | Read the result from `resultsUrl` or `statusUrl`. |
| `400` | A parameter is missing or invalid. | Fix the request; the message says what is wrong. |
| `401` | No valid API key. | See [Authentication](/docs/get-started/authentication). |
| `403` | Scrape, Bot View, Brand and Site Map: the site's robots.txt disallows Rankfield-User, or the site is excluded. | Don't retry. |
| `404` | Not found: the job id is unknown or expired. A domain that isn't in our link graph yet is not an error: it answers `200` with `"inGraph": false`. | Don't retry. |
| `409` | Conflict: a download of a job that is not finished, or an `Idempotency-Key` reused with a different body. | Wait for the job, or use a new key. |
| `410` | Gone: a page job's results expired (they are kept for 24 hours). | Start a new job. |
| `413` | Too many URLs in one job. | Split the list. |
| `415` | Scrape, Bot View, Brand and Site Map: the page is not HTML or text. | Don't retry. |
| `422` | The website answered with an error or timed out, or its address is not public. | Retry only when `error.retryable` is `true`. |
| `429` | The server is busy, or (Scrape, Bot View, Brand and Site Map) the shared batch queue is full when you start a job. | Wait for the `Retry-After` header, then retry. |
| `500` | Scrape, Bot View, Brand and Site Map: our bug. | Retry. |
| `502` | A lookup behind the API failed, or the website could not be reached. | Retry later. |
| `503` | The service is busy or paused. | Wait for `Retry-After`, then retry. |
| `504` | The website did not answer within `timeout`, or the call waited its turn for that website (`sitePace`). | Retry, or allow a longer `timeout`. |

A `404` or `500` from a website you asked us to fetch is not an error from us: the page's own status is in the answer's `status` field.

## Error bodies

Every error is JSON. The shape depends on the endpoint family:

| Endpoints | Body |
|---|---|
| Site Strength, Referring Domains, exports, Link Extraction | `{"error": {"message": "..."}}`. A page that failed adds `code` (such as `SOURCE_HTTP_404`) and `retryable`. |
| Scrape, Bot View, Brand and Site Map | `{"error": {"code": "...", "message": "...", "details": {...}}}`. `code` is stable, such as `robots_disallowed` or `busy`. |
| Suggest (Bing, DuckDuckGo, Yahoo) | `{"error": "..."}`: the message is a string. |

To handle all of them in one place, read the message like this:

```javascript
const body = await response.json();
const message = typeof body.error === "string" ? body.error : body.error?.message;
```

## Retries

- Retry `429`, `503` and `504` after the number of seconds in `Retry-After` (or 2 seconds when it is missing), and back off if it happens again.
- Retry `502` and a `422` with `"retryable": true` a few times at most.
- Never retry `400`, `401`, `403`, `404`, `413` or `415` unchanged.
- Repeat a job submission with the same `Idempotency-Key` and body: you get the same job back, not a second one.

Every answer carries an `x-request-id` header. Quote it when you report a problem.


---

# Rate limits
Source: https://rankfield.dev/docs/get-started/rate-limits

See how much one Rankfield request or job can hold, what a busy server answers, and how to avoid 429 errors.

No endpoint has per-key rate limits or quotas for now. Every endpoint answers `429` with `Retry-After` when the server is busy; the table shows how much one job can hold.

## Per endpoint

| Endpoint | One request or job | When the server is busy |
|---|---|---|
| [Site Strength](/docs/site-strength/get-site-strength) | One domain per request. | `429` with `Retry-After` |
| [Referring Domains](/docs/referring-domains/get-referring-domains), [All Referring Domains](/docs/referring-domains/list-referrers), [Referrer Profile](/docs/referring-domains/get-referrer-profile) | CSV and JSONL lists over 50,000 rows become export jobs. | `429` with `Retry-After` |
| [Export jobs](/docs/referring-domains/start-an-export-job) | One domain's full list per job; one job at a time per key. | `409` while another export runs |
| [Link Extraction](/docs/link-extraction/extract-links) | Up to 600 URLs per job; a single-page request is a one-URL job. | `429` with `Retry-After` |
| [Suggest](/docs/suggest) (each engine) | Up to 10,000 keywords per job. | `429`, or `503` while an engine cools down, with `Retry-After` |
| [Scrape](/docs/scrape/scrape-a-page) | Up to 10,000 URLs per job. | `429` `busy` with `Retry-After` |
| [Bot View](/docs/bot-view/check-a-page) | Up to 10,000 URLs per job. | `429` `busy` with `Retry-After` |
| [Brand](/docs/brand/get-a-brand) | Up to 10,000 domains per job. | `429` `busy` with `Retry-After` |
| [Site Map](/docs/map/map-a-site) | Up to 1,000 domains per job. | `429` `busy` with `Retry-After` |

## When you get a 429

The server is busy. The answer has a `Retry-After` header in seconds: wait that long, then send the request again.

On Scrape, Bot View, Brand and Site Map, jobs from all keys share one queue: starting a job while it is full also answers `429` `busy`, with `Retry-After` of 60 seconds.

Suggest engines also show what you have used: `GET /v1/bing/suggest/usage` (or `/v1/ddg/suggest/usage`, `/v1/yahoo/search-predictions/usage`). See [Get usage and capacity](/docs/suggest/get-usage-and-capacity).

## Avoid 429 errors

- For many URLs or keywords, start a [batch job](/docs/get-started/batch-jobs) instead of sending many single requests.
- Reuse answers: page endpoints accept `maxAge`, which returns a recent stored copy instead of fetching the page again.


---

# Batch jobs
Source: https://rankfield.dev/docs/get-started/batch-jobs

Send many URLs, domains or keywords in one Rankfield batch job, follow its progress, and read results as they finish.

Use a single request for one URL or keyword. Use a batch job when you have many: one request starts the job, and you read results as each item finishes, without holding a connection open.

## How a job works

1. **Start it.** `POST` the list to the endpoint's `/jobs` path. The answer is `202` with the job's `id`.
2. **Follow it.** `GET /jobs/{id}` reports its status and how many items are done.
3. **Read results.** `GET /jobs/{id}/results` returns finished items in the order they finish, each with its position in your list. Pass the returned cursor back to read the next ones.
4. **Download** (where offered). When the job is complete, `?format=jsonl` or `?format=csv` streams everything at once.

Send an `Idempotency-Key` header when you start a job. If your request times out and you send it again with the same key and body, you get the same job back instead of a second one.

## The three job styles

Rankfield's endpoint families each keep their own job format:

| | Link Extraction | Suggest | Scrape, Bot View, Brand and Site Map |
|---|---|---|---|
| Body | `{"urls": [...]}`, up to 600 | `{"queries": [...]}`, up to 10,000 | `{"items": [{...}]}`, up to 10,000 (Map: 1,000) |
| `Idempotency-Key` | Optional | Required | Required |
| Read results | `nextCursor` until it is `null` | `cursor` while `hasMore` is true | `cursor` while `hasMore` is true |
| Deadline | `delivery`: `standard` (330 s) or `priority` (90 s) | `delivery`: `standard` (300 s), `priority` (60 s) or `live` (6 s) | None: 16 items run at a time |
| Cancel | Not available | `POST /jobs/{id}/cancel` | `POST /jobs/{id}/cancel` |
| Kept for | 24 hours | 24 hours | 24 hours after the job finishes |

Link Extraction fetches up to 5 pages a second from one website, so about 400 pages of one site fit a `priority` job and about 1,500 a `standard` one. For many pages of one site, use `standard`.

Each endpoint's pages show its exact requests and answers, for example [Start a Link Extraction job](/docs/link-extraction/start-a-job).

## Example: read results as they finish

```python Python
import os, time, requests

BASE = "https://rankfield.dev/v1/html/link-extraction"
HEADERS = {"Authorization": f"Bearer {os.environ['RANKFIELD_API_KEY']}"}

job = requests.post(f"{BASE}/jobs", headers={**HEADERS, "Idempotency-Key": "crawl-2026-10-25"},
                    json={"urls": ["https://example.com/", "https://www.iana.org/help/example-domains"]}).json()

cursor = 0
while cursor is not None:
    page = requests.get(f"{BASE}/jobs/{job['id']}/results", headers=HEADERS,
                        params={"cursor": cursor, "wait": 20}).json()
    for result in page["pages"]:
        print(result["url"], result["counts"]["links"] if result["ok"] else result["error"]["message"])
    cursor = page["nextCursor"]
```

```javascript JavaScript
const BASE = "https://rankfield.dev/v1/html/link-extraction";
const headers = { Authorization: `Bearer ${process.env.RANKFIELD_API_KEY}` };

const job = await (await fetch(`${BASE}/jobs`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": "crawl-2026-10-25" },
  body: JSON.stringify({ urls: ["https://example.com/", "https://www.iana.org/help/example-domains"] }),
})).json();

for (let cursor = 0; cursor !== null; ) {
  const page = await (await fetch(`${BASE}/jobs/${job.id}/results?cursor=${cursor}&wait=20`, { headers })).json();
  for (const result of page.pages) console.log(result.url, result.ok ? result.counts.links : result.error.message);
  cursor = page.nextCursor;
}
```


---

# Site Strength
Source: https://rankfield.dev/docs/site-strength

Get Site Strength, Rankfield's 0–100 authority score for a domain, calculated from the Rankfield web graph.

Site Strength rates how strongly the rest of the web links to a domain, on a 0–100 scale. It comes from the domain's ranks in the Rankfield web graph, so you can compare any two domains in the graph the same way.

One request returns one score. There are no per-key limits.

## Pages

- [Get Site Strength](/docs/site-strength/get-site-strength): Get the Site Strength of a domain: a 0–100 score of how strongly the web links to it, from the Rankfield web graph.
- [How Site Strength works](/docs/site-strength/how-site-strength-works): Learn how Rankfield calculates Site Strength from web graph ranks, and how to compare and interpret scores.
:::


---

# Get Site Strength
Source: https://rankfield.dev/docs/site-strength/get-site-strength

Get the Site Strength of a domain: a 0–100 score of how strongly the web links to it, from the Rankfield web graph.

`GET https://rankfield.dev/v1/domains/{domain}/site-strength`

```bash cURL
curl 'https://rankfield.dev/v1/domains/wikipedia.org/site-strength' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/domains/wikipedia.org/site-strength",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/domains/wikipedia.org/site-strength", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "domain": "wikipedia.org",
  "siteStrength": 100
}
```

```json 200 (not in the graph)
{
  "domain": "example-not-in-graph.dev",
  "inGraph": false,
  "siteStrength": 0
}
```

```json 400
{
  "error": {
    "message": "Invalid domain"
  }
}
```

```json 401
{
  "error": {
    "message": "A valid API key is required"
  }
}
```

## 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 |
|---|---|---|---|---|
| `domain` | string | Yes | – | The domain, such as `example.com`. Case is ignored, a leading `www.` is removed, and a full URL is read as its host. URL-encode it in the path. |

## Response

| Field | Type | Description |
|---|---|---|
| `domain` | string | The domain as it was looked up, after normalising. |
| `inGraph` | boolean | Only when the domain isn't in our link graph yet: `false`, with zeros. Absent otherwise. |
| `siteStrength` | integer | 0–100. Higher means stronger link evidence in the graph. |

The score is Rankfield's own. It is not Moz Domain Authority or Ahrefs Domain Rating, and it does not estimate traffic. [How Site Strength works](/docs/site-strength/how-site-strength-works) explains how it is calculated.

## Errors

| Status | When |
|---|---|
| 400 | The domain is not a valid domain name, or a parameter is out of range. |
| 401 | No valid API key. |
| 429 | Too many requests at once; wait for `Retry-After`. |
| 502 | The graph lookup behind the API failed. Retry later. |
| 503 | The graph index is unavailable for a moment. Retry after `Retry-After`. |

## Limits

No per-key limits. When the server is busy you get `429` with `Retry-After`.

## Related

- [Get Referring Domains](/docs/referring-domains/get-referring-domains): how many domains link to this one, with the 20 strongest.
- [Get Referrer Profile](/docs/referring-domains/get-referrer-profile): the Site Strength of every referring domain, in ten ranges.

## MCP

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


---

# How Site Strength works
Source: https://rankfield.dev/docs/site-strength/how-site-strength-works

Learn how Rankfield calculates Site Strength from web graph ranks, and how to compare and interpret scores.

## What the score measures

Site Strength combines two standard ranks of each domain in the web graph: PageRank and harmonic centrality. Both rise when many domains link to a domain, and when the domains linking to it are themselves well linked.

Rankfield turns the two rank positions into a logarithmic scale and maps them to 0–100 with a calibration checked against held-out data. The mapping only goes up: a better rank never gives a lower score.

## Read it correctly

- Compare scores within the same release. Every answer is scored with the release in [Get Dataset Status](/docs/data/get-dataset-status).
- Treat a difference of a few points as noise. The score summarises a graph model.
- The score is not a probability, a share of the web or a count of backlinks.
- It does not measure traffic, rankings, relevance or trust.
- It is not interchangeable with Moz Domain Authority, Ahrefs Domain Rating or any other vendor's score: they use other data and methods.

## Which domains have a score

Only domains in the current web graph release, about 118 million. Others answer `200` with `"inGraph": false` and a `siteStrength` of `0`: the domain isn't in our link graph yet, so treat it as no data, not a score. The field is absent for every other domain, and a malformed domain gets `400`. A domain can be missing because the crawl data the graph is built from has no page linking to it, not because it has no links. [Coverage and dates](/docs/data/coverage-and-dates) has the details.


---

# Referring Domains
Source: https://rankfield.dev/docs/referring-domains

Count the domains that link to a site, list every one of them with its Site Strength, and export the full list as CSV or JSONL.

A referring domain is a distinct domain that links to the domain you ask about, as recorded in the Rankfield web graph. These endpoints give you the count, the full list in either direction, its Site Strength profile, and exports of any size.

| You want | Use |
|---|---|
| The count and the 20 strongest referring domains | [Get Referring Domains](/docs/referring-domains/get-referring-domains) |
| Every referring domain, page by page | [List All Referring Domains](/docs/referring-domains/list-referrers) |
| Every domain the site links to | [List Outbound Domains](/docs/referring-domains/list-outbound-domains) |
| How many referring domains fall in each Site Strength range | [Get Referrer Profile](/docs/referring-domains/get-referrer-profile) |
| A list over 50,000 rows as one file | [Start an export job](/docs/referring-domains/start-an-export-job) |

The lists hold domains, not pages: source URLs and anchor text are not part of the graph.

## Pages

- [Get Referring Domains](/docs/referring-domains/get-referring-domains): Get how many distinct domains link to a domain, and the 20 strongest of them with their Site Strength.
- [List All Referring Domains](/docs/referring-domains/list-referrers): List every domain that links to a domain, with its Site Strength, page by page or as one CSV or JSONL file.
- [List Outbound Domains](/docs/referring-domains/list-outbound-domains): List every domain a site links to, with its Site Strength, page by page or as one CSV or JSONL file.
- [Get Referrer Profile](/docs/referring-domains/get-referrer-profile): Get how a domain's referring domains spread across ten Site Strength ranges, counted over the complete list.
- [Start an export job](/docs/referring-domains/start-an-export-job): Export every referring or outbound domain of a site as a CSV or JSONL file, however long the list.
- [Get an export job](/docs/referring-domains/get-an-export-job): Check an export job's progress and, once it is complete, its row count, file parts, checksums and download link.
:::


---

# Get Referring Domains
Source: https://rankfield.dev/docs/referring-domains/get-referring-domains

Get how many distinct domains link to a domain, and the 20 strongest of them with their Site Strength.

`GET https://rankfield.dev/v1/domains/{domain}/referring-domains`

```bash cURL
curl 'https://rankfield.dev/v1/domains/cloro.dev/referring-domains' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/domains/cloro.dev/referring-domains",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/domains/cloro.dev/referring-domains", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "domain": "cloro.dev",
  "referringDomains": 68,
  "topReferrers": [
    { "domain": "vercel.app", "siteStrength": 89, "observations": 1 },
    { "domain": "it.com", "siteStrength": 88, "observations": 1 },
    { "domain": "langchain.com", "siteStrength": 75, "observations": 1 },
    { "domain": "artdaily.com", "siteStrength": 70, "observations": 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 |
|---|---|---|---|---|
| `domain` | string | Yes | – | The domain, such as `example.com`. Case is ignored, a leading `www.` is removed, and a full URL is read as its host. URL-encode it in the path. |

## Response

| Field | Type | Description |
|---|---|---|
| `domain` | string | The domain as it was looked up. |
| `inGraph` | boolean | Only when the domain isn't in our link graph yet: `false`, with zeros. Absent otherwise. |
| `referringDomains` | integer \| null | How many distinct domains link to it in the graph. `null` when the count is unavailable: keep it as unknown, not zero. |
| `topReferrers` | array | Up to 20 referring domains, strongest first (the example shows 4). |
| `topReferrers[].domain` | string | The linking domain. |
| `topReferrers[].siteStrength` | integer \| null | Its Site Strength, `null` when it has no score. |
| `topReferrers[].observations` | integer | `1` marks one domain-to-domain link in the graph. It is not a count of pages or backlinks. |

To get every referring domain, not only 20, use [List All Referring Domains](/docs/referring-domains/list-referrers).

## Errors

| Status | When |
|---|---|
| 400 | The domain is not a valid domain name, or a parameter is out of range. |
| 401 | No valid API key. |
| 429 | Too many requests at once; wait for `Retry-After`. |
| 502 | The graph lookup behind the API failed. Retry later. |
| 503 | The graph index is unavailable for a moment. Retry after `Retry-After`. |

## Limits

No per-key limits. When the server is busy you get `429` with `Retry-After`.

## MCP

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


---

# List All Referring Domains
Source: https://rankfield.dev/docs/referring-domains/list-referrers

List every domain that links to a domain, with its Site Strength, page by page or as one CSV or JSONL file.

`GET https://rankfield.dev/v1/domains/{domain}/referrers`

```bash cURL
curl 'https://rankfield.dev/v1/domains/wikipedia.org/referrers?limit=3' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/domains/wikipedia.org/referrers?limit=3",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/domains/wikipedia.org/referrers?limit=3", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "domain": "wikipedia.org",
  "crawlRelease": "2026-may-jun-jul",
  "buildId": "graph-2026mayjunjul-v3",
  "asOf": "2026-08-19T00:00:00Z",
  "source": "Rankfield web graph",
  "siteStrengthVersion": "authority-continuous-counts-0.3.1",
  "totalGraphRelationships": 2154598,
  "publishedSummaryCount": 2154598,
  "countReconciled": true,
  "evidenceCoverage": "domain-graph",
  "sort": "strength_desc",
  "minSiteStrength": 0,
  "referrers": [
    { "domain": "adobe.com", "siteStrength": 100 },
    { "domain": "amazon.com", "siteStrength": 100 },
    { "domain": "amazonaws.com", "siteStrength": 100 }
  ],
  "nextCursor": "eyJ2IjoxLCJkb21haW4iOiJ3aWtpcGVkaWEub3JnIiwiZGlyZWN0aW9uIjoiaW5ib3VuZCIsInJlbGVhc2UiOiIyMDI2LW1heS1qdW4tanVsIiwiYnVpbGRJZCI6ImdyYXBoLTIwMjZtYXlqdW5qdWwtdjMiLCJhc09mIjoiMjAyNi0wOC0xOVQwMDowMDowMFoiLCJtaW5TaXRlU3RyZW5ndGgiOjAsInNvcnQiOiJzdHJlbmd0aF9kZXNjIiwicG9zaXRpb24iOjN9.488e7b22c11bc97ca2bf07159ab6406d7dbb326ace55b098cb233387413ea504"
}
```

```csv 200 CSV
domain,siteStrength,crawlRelease,asOf,evidenceCoverage
vercel.app,89,2026-may-jun-jul,2026-08-19T00:00:00Z,domain-graph
it.com,88,2026-may-jun-jul,2026-08-19T00:00:00Z,domain-graph
langchain.com,75,2026-may-jun-jul,2026-08-19T00:00:00Z,domain-graph
```

## 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 |
|---|---|---|---|---|
| `domain` | string | Yes | – | The domain, such as `example.com`. Case is ignored, a leading `www.` is removed, and a full URL is read as its host. URL-encode it in the path. |

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `limit` | integer | No | `100` | Rows per page, 1–1,000. |
| `cursor` | string | No | – | The `nextCursor` of the previous page. Leave it out for the first page. |
| `minSiteStrength` | integer | No | `0` | Only domains with at least this Site Strength, 0–100. |
| `sort` | string | No | `strength_desc` | `strength_desc` (strongest first) or `strength_asc`. |
| `format` | string | No | `json` | `json`, or `csv` or `jsonl` to download the whole list in one answer (no `cursor`). |

## Response

| Field | Type | Description |
|---|---|---|
| `domain` | string | The domain you asked about. |
| `inGraph` | boolean | Only when the domain isn't in our link graph yet: `false`, with an empty list. Absent otherwise. |
| `crawlRelease` | string | The web graph release the list comes from, such as `2026-may-jun-jul`. |
| `asOf` | string | The release date (UTC). |
| `buildId` | string | The index build. A cursor only works with the build it came from. |
| `siteStrengthVersion` | string | The Site Strength scoring version. |
| `totalGraphRelationships` | integer | How many domains are in the whole list, before `minSiteStrength`. |
| `evidenceCoverage` | string | `domain-graph`: domain-to-domain links. Source page URLs and anchor text are not part of this list. |
| `sort` | string | The order used. |
| `minSiteStrength` | integer | The filter used. |
| `referrers` | array | This page's domains, each `{domain, siteStrength}`. `siteStrength` is `null` when the domain has no score. |
| `nextCursor` | string \| null | Pass it as `cursor` for the next page. `null` on the last page. |

The answer also carries `source`, and `publishedSummaryCount` with `countReconciled`: whether `totalGraphRelationships` matches the count in [Get Referring Domains](/docs/referring-domains/get-referring-domains).

## Page through the list

Request the first page, then pass each `nextCursor` back as `cursor` until it is `null`. Keep `minSiteStrength` and `sort` the same on every page: a cursor is tied to them and to the release, and a changed filter answers `400` (start again without `cursor`).

## Download the whole list

Add `format=csv` or `format=jsonl` to get every row in one answer, as a file download (`Content-Disposition: attachment`). CSV columns: `domain, siteStrength, crawlRelease, asOf, evidenceCoverage`.

When the domain has more than 50,000 referring domains, the answer is `202` with an export job instead: follow it as in [Get an export job](/docs/referring-domains/get-an-export-job).

## Errors

| Status | When |
|---|---|
| 400 | The domain is not a valid domain name, or a parameter is out of range. |
| 401 | No valid API key. |
| 429 | Too many requests at once; wait for `Retry-After`. |
| 502 | The graph lookup behind the API failed. Retry later. |
| 503 | The graph index is unavailable for a moment. Retry after `Retry-After`. |

## Limits

No per-key limits. When the server is busy you get `429` with `Retry-After`. File downloads over 50,000 rows become [export jobs](/docs/referring-domains/start-an-export-job), one at a time per key.

## MCP

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


---

# List Outbound Domains
Source: https://rankfield.dev/docs/referring-domains/list-outbound-domains

List every domain a site links to, with its Site Strength, page by page or as one CSV or JSONL file.

`GET https://rankfield.dev/v1/domains/{domain}/outbound-domains`

```bash cURL
curl 'https://rankfield.dev/v1/domains/wikipedia.org/outbound-domains?limit=3' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/domains/wikipedia.org/outbound-domains?limit=3",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/domains/wikipedia.org/outbound-domains?limit=3", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "domain": "wikipedia.org",
  "crawlRelease": "2026-may-jun-jul",
  "buildId": "graph-2026mayjunjul-v3",
  "asOf": "2026-08-19T00:00:00Z",
  "source": "Rankfield web graph",
  "siteStrengthVersion": "authority-continuous-counts-0.3.1",
  "totalGraphRelationships": 1470604,
  "publishedSummaryCount": null,
  "countReconciled": null,
  "evidenceCoverage": "domain-graph",
  "sort": "strength_desc",
  "minSiteStrength": 0,
  "destinations": [
    { "domain": "adobe.com", "siteStrength": 100 },
    { "domain": "amazon.com", "siteStrength": 100 },
    { "domain": "amazonaws.com", "siteStrength": 100 }
  ],
  "nextCursor": "eyJ2IjoxLCJkb21haW4iOiJ3aWtpcGVkaWEub3JnIiwiZGlyZWN0aW9uIjoib3V0Ym91bmQiLCJyZWxlYXNlIjoiMjAyNi1tYXktanVuLWp1bCIsImJ1aWxkSWQiOiJncmFwaC0yMDI2bWF5anVuanVsLXYzIiwiYXNPZiI6IjIwMjYtMDgtMTlUMDA6MDA6MDBaIiwibWluU2l0ZVN0cmVuZ3RoIjowLCJzb3J0Ijoic3RyZW5ndGhfZGVzYyIsInBvc2l0aW9uIjozfQ.50bb56edb0361191e86228dccfc29b01710a19ce5c7c654d89ce920a2f59927f"
}
```

The same list as [List All Referring Domains](/docs/referring-domains/list-referrers), in the other direction: the domains that the site links to.

## 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 |
|---|---|---|---|---|
| `domain` | string | Yes | – | The domain, such as `example.com`. Case is ignored, a leading `www.` is removed, and a full URL is read as its host. URL-encode it in the path. |

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `limit` | integer | No | `100` | Rows per page, 1–1,000. |
| `cursor` | string | No | – | The `nextCursor` of the previous page. Leave it out for the first page. |
| `minSiteStrength` | integer | No | `0` | Only domains with at least this Site Strength, 0–100. |
| `sort` | string | No | `strength_desc` | `strength_desc` (strongest first) or `strength_asc`. |
| `format` | string | No | `json` | `json`, or `csv` or `jsonl` to download the whole list in one answer (no `cursor`). |

## Response

| Field | Type | Description |
|---|---|---|
| `domain` | string | The domain you asked about. |
| `inGraph` | boolean | Only when the domain isn't in our link graph yet: `false`, with an empty list. Absent otherwise. |
| `crawlRelease` | string | The web graph release the list comes from, such as `2026-may-jun-jul`. |
| `asOf` | string | The release date (UTC). |
| `buildId` | string | The index build. A cursor only works with the build it came from. |
| `siteStrengthVersion` | string | The Site Strength scoring version. |
| `totalGraphRelationships` | integer | How many domains are in the whole list, before `minSiteStrength`. |
| `evidenceCoverage` | string | `domain-graph`: domain-to-domain links. Source page URLs and anchor text are not part of this list. |
| `sort` | string | The order used. |
| `minSiteStrength` | integer | The filter used. |
| `destinations` | array | This page's domains, each `{domain, siteStrength}`. `siteStrength` is `null` when the domain has no score. |
| `nextCursor` | string \| null | Pass it as `cursor` for the next page. `null` on the last page. |

`publishedSummaryCount` and `countReconciled` are always `null` here: there is no separate outbound count to check against.

Paging, CSV and JSONL work as in [List All Referring Domains](/docs/referring-domains/list-referrers). Over 50,000 rows, a file download becomes an export job.

## Errors

| Status | When |
|---|---|
| 400 | The domain is not a valid domain name, or a parameter is out of range. |
| 401 | No valid API key. |
| 429 | Too many requests at once; wait for `Retry-After`. |
| 502 | The graph lookup behind the API failed. Retry later. |
| 503 | The graph index is unavailable for a moment. Retry after `Retry-After`. |

## Limits

No per-key limits. When the server is busy you get `429` with `Retry-After`. File downloads over 50,000 rows become [export jobs](/docs/referring-domains/start-an-export-job), one at a time per key.

## MCP

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


---

# Get Referrer Profile
Source: https://rankfield.dev/docs/referring-domains/get-referrer-profile

Get how a domain's referring domains spread across ten Site Strength ranges, counted over the complete list.

`GET https://rankfield.dev/v1/domains/{domain}/referrer-profile`

```bash cURL
curl 'https://rankfield.dev/v1/domains/wikipedia.org/referrer-profile' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/domains/wikipedia.org/referrer-profile",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/domains/wikipedia.org/referrer-profile", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "domain": "wikipedia.org",
  "crawlRelease": "2026-may-jun-jul",
  "asOf": "2026-08-19T00:00:00Z",
  "buildId": "graph-2026mayjunjul-v3",
  "siteStrengthVersion": "authority-continuous-counts-0.3.1",
  "evidenceCoverage": "domain-graph",
  "totalGraphReferringDomains": 2154598,
  "scoreDistribution": [
    { "minSiteStrength": 0, "maxSiteStrength": 9, "referringDomains": 453583, "share": 0.21051862110704642 },
    { "minSiteStrength": 10, "maxSiteStrength": 19, "referringDomains": 820486, "share": 0.3808069997280235 },
    { "minSiteStrength": 20, "maxSiteStrength": 29, "referringDomains": 528569, "share": 0.24532140102237168 },
    { "minSiteStrength": 30, "maxSiteStrength": 39, "referringDomains": 218766, "share": 0.10153448578342689 },
    { "minSiteStrength": 40, "maxSiteStrength": 49, "referringDomains": 85750, "share": 0.039798607443244635 },
    { "minSiteStrength": 50, "maxSiteStrength": 59, "referringDomains": 33062, "share": 0.015344857834268852 },
    { "minSiteStrength": 60, "maxSiteStrength": 69, "referringDomains": 10674, "share": 0.004954056394742778 },
    { "minSiteStrength": 70, "maxSiteStrength": 79, "referringDomains": 2830, "share": 0.0013134700765525635 },
    { "minSiteStrength": 80, "maxSiteStrength": 89, "referringDomains": 700, "share": 0.0003248865913734256 },
    { "minSiteStrength": 90, "maxSiteStrength": 100, "referringDomains": 178, "share": 0.0000826140189492425 }
  ],
  "unscoredReferringDomains": 0,
  "unscoredShare": 0
}
```

## 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 |
|---|---|---|---|---|
| `domain` | string | Yes | – | The domain, such as `example.com`. Case is ignored, a leading `www.` is removed, and a full URL is read as its host. URL-encode it in the path. |

## Response

| Field | Type | Description |
|---|---|---|
| `domain` | string | The domain you asked about. |
| `inGraph` | boolean | Only when the domain isn't in our link graph yet: `false`, with empty ranges. Absent otherwise. |
| `crawlRelease`, `asOf`, `buildId`, `siteStrengthVersion` | string | Which graph release and scoring version the profile comes from. |
| `totalGraphReferringDomains` | integer | Every referring domain in the graph. |
| `scoreDistribution` | array | Ten ranges: `minSiteStrength`, `maxSiteStrength`, the `referringDomains` in that range and their `share` of the total (0–1). |
| `unscoredReferringDomains` | integer | Referring domains with no Site Strength. |
| `unscoredShare` | number | Their share of the total (0–1). |

The profile is a count, not a quality or spam verdict.

## Errors

| Status | When |
|---|---|
| 400 | The domain is not a valid domain name, or a parameter is out of range. |
| 401 | No valid API key. |
| 429 | Too many requests at once; wait for `Retry-After`. |
| 502 | The graph lookup behind the API failed. Retry later. |
| 503 | The graph index is unavailable for a moment. Retry after `Retry-After`. |

## Limits

No per-key limits. When the server is busy you get `429` with `Retry-After`.

## MCP

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


---

# Start an export job
Source: https://rankfield.dev/docs/referring-domains/start-an-export-job

Export every referring or outbound domain of a site as a CSV or JSONL file, however long the list.

`POST https://rankfield.dev/v1/jobs`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"referrers-export","domain":"cloro.dev","format":"csv"}'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/jobs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"kind": "referrers-export", "domain": "cloro.dev", "format": "csv"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"kind":"referrers-export","domain":"cloro.dev","format":"csv"}),
});
console.log(await response.json());
```

```json 202
{
  "id": "09aecabd-2230-4552-962a-c7a777724adb",
  "status": "queued",
  "kind": "referrers-export",
  "domain": "cloro.dev",
  "release": "2026-may-jun-jul",
  "buildId": "graph-2026mayjunjul-v3",
  "totalGraphRelationships": 68,
  "expiresAt": "2026-11-01T14:33:49.828Z",
  "statusUrl": "/v1/jobs/09aecabd-2230-4552-962a-c7a777724adb"
}
```

Use an export job for lists of any size. For up to 50,000 rows, `?format=csv` on [List All Referring Domains](/docs/referring-domains/list-referrers) is quicker.

## Parameters

### Headers

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

### Body

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `kind` | string | Yes | – | `referrers-export` (domains linking to it) or `outbound-export` (domains it links to). |
| `domain` | string | Yes | – | The domain, as for [Get Site Strength](/docs/site-strength/get-site-strength). |
| `format` | string | No | `csv` | `csv` or `jsonl`. |
| `minSiteStrength` | integer | No | `0` | Only domains with at least this Site Strength, 0–100. |
| `sort` | string | No | `strength_desc` | `strength_desc` or `strength_asc`. |

## Response

`202` with the job's `id`, `status` (`queued`), `totalGraphRelationships`, `expiresAt` and `statusUrl`. Follow `statusUrl` with [Get an export job](/docs/referring-domains/get-an-export-job).

For a domain that isn't in our link graph yet, the job is created already `completed`, with `"inGraph": false` and no rows: the file holds only the CSV header (or nothing, for JSONL).

## Errors

| Status | When |
|---|---|
| 400 | `kind`, `domain`, `format`, `minSiteStrength` or `sort` is invalid. |
| 401 | No valid API key. |
| 409 | This key already has an export running. Wait for it to finish. |
| 503 | The export service or the graph index is unavailable. Retry later. |

## Limits

No daily limit; one export job at a time per key. Finished exports are kept for 7 days.

## MCP

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


---

# Get an export job
Source: https://rankfield.dev/docs/referring-domains/get-an-export-job

Check an export job's progress and, once it is complete, its row count, file parts, checksums and download link.

`GET https://rankfield.dev/v1/jobs/{id}`

```bash cURL
curl 'https://rankfield.dev/v1/jobs/09aecabd-2230-4552-962a-c7a777724adb' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/jobs/09aecabd-2230-4552-962a-c7a777724adb",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/jobs/09aecabd-2230-4552-962a-c7a777724adb", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "id": "09aecabd-2230-4552-962a-c7a777724adb",
  "kind": "referrers-export",
  "status": "completed",
  "error": null,
  "domain": "cloro.dev",
  "crawlRelease": "2026-may-jun-jul",
  "buildId": "graph-2026mayjunjul-v3",
  "totalGraphRelationships": 68,
  "scannedRelationships": 68,
  "exportedRows": 68,
  "createdAt": "2026-10-25T14:33:49.828Z",
  "updatedAt": "2026-10-25T14:33:49.882Z",
  "expiresAt": "2026-11-01T14:33:49.878Z",
  "result": {
    "schemaVersion": 1,
    "id": "09aecabd-2230-4552-962a-c7a777724adb",
    "domain": "cloro.dev",
    "direction": "inbound",
    "format": "csv",
    "minSiteStrength": 0,
    "sort": "strength_desc",
    "crawlRelease": "2026-may-jun-jul",
    "buildId": "graph-2026mayjunjul-v3",
    "asOf": "2026-08-19T00:00:00Z",
    "evidenceCoverage": "domain-graph",
    "pageLevelEvidence": "unavailable",
    "totalGraphRelationships": 68,
    "rowCount": 68,
    "byteCount": 5266,
    "partsDigestSha256": "9f373791615a5f16da748734084934d74808ab4a72fa00a874fe1a885491a147",
    "parts": [
      {
        "index": 0,
        "key": "public-exports/09aecabd-2230-4552-962a-c7a777724adb/parts/00000.csv",
        "rows": 68,
        "bytes": 5266,
        "sha256": "88a2e7713dc632a3d69211919e444b2cfc49ee0e8fa74233b1786a1176edfdf2"
      }
    ],
    "completedAt": "2026-10-25T14:33:49.878Z",
    "expiresAt": "2026-11-01T14:33:49.878Z"
  },
  "downloadUrl": "/v1/jobs/09aecabd-2230-4552-962a-c7a777724adb/download",
  "partUrlTemplate": "/v1/jobs/09aecabd-2230-4552-962a-c7a777724adb/parts/{index}"
}
```

## 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 from [Start an export job](/docs/referring-domains/start-an-export-job). |

## Response

| Field | Type | Description |
|---|---|---|
| `status` | string | `queued`, `running`, `completed`, `failed` or `cancelled`. |
| `inGraph` | boolean | Only when the domain isn't in our link graph yet: `false`, and the export has no rows. Absent otherwise. |
| `scannedRelationships` | integer | How much of the list has been read so far, out of `totalGraphRelationships`. |
| `exportedRows` | integer | Rows written so far (after `minSiteStrength`). |
| `error` | string \| null | Why the job failed. |
| `result` | object \| null | Once completed: the file's `rowCount`, `byteCount`, `parts` (each with `rows`, `bytes` and `sha256`) and `partsDigestSha256`. |
| `downloadUrl` | string | Once completed: the whole file in one download. |
| `partUrlTemplate` | string | Once completed: one part at a time; replace `{index}`. |

## Download the file

`GET /v1/jobs/{id}/download` streams every part as one file. For very large exports, download `/v1/jobs/{id}/parts/{index}` one by one and check each part's `sha256`, so a broken connection only costs one part.

Both answer `409` until the job is `completed`.

## Cancel or resume

- `DELETE /v1/jobs/{id}` cancels a queued or running job (`409` once it has finished).
- `POST /v1/jobs/{id}/resume` restarts a `failed` job from where it stopped.

## Errors

| Status | When |
|---|---|
| 401 | No valid API key. |
| 404 | No job with this id for this key, or it has expired. |
| 409 | Download or cancel of a job in the wrong state. |

## MCP

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


---

# Suggest
Source: https://rankfield.dev/docs/suggest

Get the autocomplete suggestions Bing, DuckDuckGo and Yahoo show for a keyword, one at a time or for up to 10,000 keywords in a job.

Each engine has its own path and the same contract: a GET for one keyword, answered at once, and jobs for keyword lists. Any Rankfield API key works, with no sign-up step.

| Engine | Base path |
|---|---|
| Bing | `/v1/bing/suggest` |
| DuckDuckGo | `/v1/ddg/suggest` |
| Yahoo | `/v1/yahoo/search-predictions` |

Job pages use Bing in their examples; replace the base path to use another engine.

## Pages

- [Get Bing suggestions](/docs/suggest/get-bing-suggestions): Get the autocomplete suggestions Bing shows for a keyword, in one of ten markets, as a JSON list.
- [Get DuckDuckGo suggestions](/docs/suggest/get-duckduckgo-suggestions): Get the autocomplete suggestions DuckDuckGo shows for a keyword, as a JSON list with the time they were collected.
- [Get Yahoo Search Predictions](/docs/suggest/get-yahoo-search-predictions): Get the search predictions Yahoo shows for a keyword, as a JSON list with the time they were collected.
- [Start a suggest job](/docs/suggest/start-a-job): Collect suggestions for up to 10,000 keywords in one job, with a delivery deadline of 6, 60 or 300 seconds.
- [Get a suggest job](/docs/suggest/get-a-job): Check a suggest job's status and how many of its keywords are done, succeeded and failed.
- [Get suggest job results](/docs/suggest/get-results): Read a suggest job's keywords as they finish, each with its engine answer, and page through them with a cursor.
- [Cancel a suggest job](/docs/suggest/cancel-a-job): Stop a running suggest job. Keywords already finished stay readable; the rest end with status 499.
- [Get usage and capacity](/docs/suggest/get-usage-and-capacity): See how many keywords your key has used today on a suggest engine, its jobs and requests by status, and the engine's delivery tiers.
:::


---

# Get Bing suggestions
Source: https://rankfield.dev/docs/suggest/get-bing-suggestions

Get the autocomplete suggestions Bing shows for a keyword, in one of ten markets, as a JSON list.

`GET https://rankfield.dev/v1/bing/suggest?query={keyword}`

```bash cURL
curl 'https://rankfield.dev/v1/bing/suggest?query=keyword%20research&market=en-US' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/bing/suggest?query=keyword%20research&market=en-US",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bing/suggest?query=keyword%20research&market=en-US", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "source": "bing-suggest",
  "query": "keyword research",
  "market": "en-US",
  "count": 17,
  "suggestions": [
    "keyword research",
    "keyword research tool",
    "keyword research tool free",
    "keyword research tips",
    "keyword research report",
    "keyword research tools seo",
    "keyword research software",
    "keyword research free",
    "keyword research for seo",
    "keyword research google",
    "keyword research and analysis",
    "keyword research seo tool",
    "keyword researcher",
    "keyword research tools for aeo in llms",
    "keyword research planner",
    "keyword research tool google",
    "keyword research meaning"
  ]
}
```

```json 401
{
  "error": "A valid API key is required"
}
```

One keyword per request, answered at once. For keyword lists, [start a job](/docs/suggest/start-a-job).

## Parameters

### Headers

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

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | Yes | – | The keyword, 1–200 printable characters. URL-encode it. |
| `market` | string | No | `en-US` | One of `en-US`, `en-GB`, `en-CA`, `en-AU`, `en-IN`, `en-NG`, `fr-FR`, `de-DE`, `es-ES`, `pt-BR`. |
| `freshness` | string | No | `fresh` | `fresh` may reuse an answer stored in the last 5 minutes (30 seconds if the list was empty); otherwise it asks the engine. `allow-stale` may also return an answer up to 35 minutes old, marked with a `Warning: 110 - "Response is stale"` header, and refreshes it in the background. |

## Response

| Field | Type | Description |
|---|---|---|
| `source` | string | `bing-suggest`. |
| `query` | string | The keyword as it was sent to the engine. |
| `market` | string | The market used. |
| `count` | integer | How many entries `suggestions` holds. |
| `suggestions` | string[] | The engine's list, in its order. |

The count varies by keyword and market. Suggestions are what the engine shows while someone types. They are not search volumes.

## Errors

| Status | When |
|---|---|
| 400 | `query` is missing, empty, over 200 characters, or another parameter is invalid. |
| 401 | No valid API key. |
| 429 | The engine is busy: its collection budget is full for the moment. Wait for `Retry-After`. |
| 502 | Bing answered with an error, or with data that couldn't be read. |
| 503 | Bing collection is paused, cooling down, timed out or unavailable. Retry after `Retry-After`. |

## Limits

No per-key limits for now. When an engine is busy it answers `429`, or `503` while it cools down, with `Retry-After`. [Get usage and capacity](/docs/suggest/get-usage-and-capacity) shows what your key has used.

## MCP

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


---

# Get DuckDuckGo suggestions
Source: https://rankfield.dev/docs/suggest/get-duckduckgo-suggestions

Get the autocomplete suggestions DuckDuckGo shows for a keyword, as a JSON list with the time they were collected.

`GET https://rankfield.dev/v1/ddg/suggest?query={keyword}`

```bash cURL
curl 'https://rankfield.dev/v1/ddg/suggest?query=keyword%20research' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/ddg/suggest?query=keyword%20research",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/ddg/suggest?query=keyword%20research", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "source": "ddg-suggest",
  "query": "keyword research",
  "market": "default",
  "endpoint": "ac-list",
  "collectedAt": "2026-10-25T14:34:00.361Z",
  "count": 8,
  "suggestions": [
    "keyword research",
    "keyword research tool free",
    "keyword research tips",
    "keyword research free",
    "keyword research report",
    "keyword research tools seo",
    "keyword researcher tool",
    "keyword research and analysis"
  ]
}
```

```json 401
{
  "error": "A valid API key is required"
}
```

One keyword per request, answered at once. For keyword lists, [start a job](/docs/suggest/start-a-job).

## Parameters

### Headers

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

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | Yes | – | The keyword, 1–200 printable characters. URL-encode it. |
| `freshness` | string | No | `fresh` | `fresh` may reuse an answer stored in the last 5 minutes (30 seconds if the list was empty); otherwise it asks the engine. `allow-stale` may also return an answer up to 35 minutes old, marked with a `Warning: 110 - "Response is stale"` header, and refreshes it in the background. |

## Response

| Field | Type | Description |
|---|---|---|
| `source` | string | `ddg-suggest`. |
| `query` | string | The keyword as it was sent to the engine. |
| `market` | string | `default`. |
| `endpoint` | string | Which DuckDuckGo source answered. |
| `collectedAt` | string | When the suggestions were collected (UTC). |
| `count` | integer | How many entries `suggestions` holds. |
| `suggestions` | string[] | The engine's list, in its order. |

DuckDuckGo has one market: `market=default`, or no market, is accepted; any other value or locale option answers `400`. Suggestions are what the engine shows while someone types. They are not search volumes.

## Errors

| Status | When |
|---|---|
| 400 | `query` is missing, empty, over 200 characters, or another parameter is invalid. |
| 401 | No valid API key. |
| 429 | The engine is busy: its collection budget is full for the moment. Wait for `Retry-After`. |
| 502 | DuckDuckGo answered with an error, or with data that couldn't be read. |
| 503 | DuckDuckGo collection is paused, cooling down, timed out or unavailable. Retry after `Retry-After`. |

## Limits

No per-key limits for now. When an engine is busy it answers `429`, or `503` while it cools down, with `Retry-After`. [Get usage and capacity](/docs/suggest/get-usage-and-capacity) shows what your key has used.

## MCP

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


---

# Get Yahoo Search Predictions
Source: https://rankfield.dev/docs/suggest/get-yahoo-search-predictions

Get the search predictions Yahoo shows for a keyword, as a JSON list with the time they were collected.

`GET https://rankfield.dev/v1/yahoo/search-predictions?query={keyword}`

```bash cURL
curl 'https://rankfield.dev/v1/yahoo/search-predictions?query=seo%20tools' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/yahoo/search-predictions?query=seo%20tools",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/yahoo/search-predictions?query=seo%20tools", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "source": "yahoo-search-predictions",
  "query": "seo tools",
  "market": "default",
  "endpoint": "gossip-us-fp",
  "collectedAt": "2026-10-25T14:34:16.607Z",
  "count": 10,
  "predictions": [
    "seo tools plagiarism checker",
    "seo tools free",
    "seo tools adda",
    "seo tools meaning",
    "seo tools for website",
    "seo tools list",
    "seo tools plagiarism",
    "seo tools centre paraphrasing tool",
    "seo tools group buy",
    "seo tools bd"
  ]
}
```

```json 401
{
  "error": "A valid API key is required"
}
```

One keyword per request, answered at once. For keyword lists, [start a job](/docs/suggest/start-a-job).

## Parameters

### Headers

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

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | Yes | – | The keyword, 1–200 printable characters. URL-encode it. |
| `freshness` | string | No | `fresh` | `fresh` may reuse an answer stored in the last 5 minutes (30 seconds if the list was empty); otherwise it asks the engine. `allow-stale` may also return an answer up to 35 minutes old, marked with a `Warning: 110 - "Response is stale"` header, and refreshes it in the background. |

## Response

| Field | Type | Description |
|---|---|---|
| `source` | string | `yahoo-search-predictions`. |
| `query` | string | The keyword as it was sent to the engine. |
| `market` | string | `default`. |
| `endpoint` | string | Which Yahoo source answered. |
| `collectedAt` | string | When the predictions were collected (UTC). |
| `count` | integer | How many entries `predictions` holds. |
| `predictions` | string[] | The engine's list, in its order. |

The list is called `predictions`, not `suggestions`. Yahoo returns no predictions for some keywords: `count` is then `0` and the list is empty. `market=default`, or no market, is accepted; any other value or locale option answers `400`. Suggestions are what the engine shows while someone types. They are not search volumes.

## Errors

| Status | When |
|---|---|
| 400 | `query` is missing, empty, over 200 characters, or another parameter is invalid. |
| 401 | No valid API key. |
| 429 | The engine is busy: its collection budget is full for the moment. Wait for `Retry-After`. |
| 502 | Yahoo answered with an error, or with data that couldn't be read. |
| 503 | Yahoo collection is paused, cooling down, timed out or unavailable. Retry after `Retry-After`. |

## Limits

No per-key limits for now. When an engine is busy it answers `429`, or `503` while it cools down, with `Retry-After`. [Get usage and capacity](/docs/suggest/get-usage-and-capacity) shows what your key has used.

## MCP

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


---

# Start a suggest job
Source: https://rankfield.dev/docs/suggest/start-a-job

Collect suggestions for up to 10,000 keywords in one job, with a delivery deadline of 6, 60 or 300 seconds.

`POST https://rankfield.dev/v1/bing/suggest/jobs`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/bing/suggest/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: keywords-2026-10-25' \
  -d '{"queries":["keyword research","seo tools"],"delivery":"priority"}'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/bing/suggest/jobs",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": "keywords-2026-10-25"},
    json={"queries": ["keyword research", "seo tools"], "delivery": "priority"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bing/suggest/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "keywords-2026-10-25",
  },
  body: JSON.stringify({"queries":["keyword research","seo tools"],"delivery":"priority"}),
});
console.log(await response.json());
```

```json 202
{
  "id": "1e3aff33-2831-4112-b934-cb727ab6c23a",
  "status": "running",
  "total": 2,
  "completed": 0,
  "succeeded": 0,
  "failed": 0,
  "createdAt": 1792938856915,
  "deadlineAt": 1792938916915,
  "completedAt": null,
  "delivery": "priority",
  "keywordCount": 2,
  "workUnits": 2
}
```

```json 400
{
  "error": "Supply an Idempotency-Key of 1–128 letters, numbers, dots, colons, underscores or hyphens"
}
```

The same request works on every engine: POST to `{base path}/jobs`.

| Engine | Base path |
|---|---|
| Bing | `/v1/bing/suggest` |
| DuckDuckGo | `/v1/ddg/suggest` |
| Yahoo | `/v1/yahoo/search-predictions` |

## 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 | Yes | – | 1–128 letters, numbers, dots, colons, underscores or hyphens. Use a new one for each new job. Sending the same key with the same body again returns the same job instead of a new one. |

### Body

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `queries` | string[] | Yes | – | 1–10,000 keywords, each 1–200 printable characters. |
| `delivery` | string | No | `standard` | When the whole job must be done: `live` (6 seconds), `priority` (60 seconds) or `standard` (300 seconds). |
| `market` | string | No | `en-US` | Bing only. One market for every keyword: see [Get Bing suggestions](/docs/suggest/get-bing-suggestions). |
| `freshness` | string | No | `fresh` | `fresh` may reuse an answer stored in the last 5 minutes (30 seconds if the list was empty); otherwise it asks the engine. `allow-stale` may also return an answer up to 35 minutes old, marked with a `Warning: 110 - "Response is stale"` header, and refreshes it in the background. |

## Delivery

A deadline covers the whole job, retries included. A job that cannot finish in time under current load is refused with `429` and a `Retry-After`, rather than accepted and finished late. Try again later or choose a longer tier. Keywords not finished by the deadline end with status `504`.

## Response

`202` with the job, as in [Get a suggest job](/docs/suggest/get-a-job). Sending the same `Idempotency-Key` and body again answers `200` with the same job and an `Idempotency-Replayed: true` header.

## Errors

| Status | When |
|---|---|
| 400 | No `Idempotency-Key`, more than 10,000 keywords, an invalid keyword, an unknown `delivery` or `freshness`, an unsupported `market`, or locale options (`language`, `country`, `client`, `cursor`, and `kl` on DuckDuckGo) on DuckDuckGo and Yahoo. |
| 401 | No valid API key. |
| 409 | The `Idempotency-Key` was used before with a different body. |
| 429 | The deadline can't be met under current load: the engine's capacity or the time left. Wait for `Retry-After`, or choose a longer tier. |

## Limits

Up to 10,000 keywords per job. No per-key limits for now. When an engine is busy it answers `429`, or `503` while it cools down, with `Retry-After`.

## MCP

On the [MCP server](/docs/agents/mcp-server), the tools for this are `start_bing_suggest_job`, `start_duckduckgo_suggest_job` and `start_yahoo_search_predictions_job`.


---

# Get a suggest job
Source: https://rankfield.dev/docs/suggest/get-a-job

Check a suggest job's status and how many of its keywords are done, succeeded and failed.

`GET https://rankfield.dev/v1/bing/suggest/jobs/{id}`

```bash cURL
curl 'https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "id": "1e3aff33-2831-4112-b934-cb727ab6c23a",
  "status": "completed",
  "total": 2,
  "completed": 2,
  "succeeded": 2,
  "failed": 0,
  "createdAt": 1792938856915,
  "deadlineAt": 1792938916915,
  "completedAt": 1792938857066,
  "delivery": "priority",
  "keywordCount": 2,
  "workUnits": 2
}
```

## 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 from [Start a suggest job](/docs/suggest/start-a-job). |

## Response

| Field | Type | Description |
|---|---|---|
| `id` | string | The job id. |
| `status` | string | `running`, `completed` or `cancelled`. |
| `total` | integer | Keywords in the job. |
| `completed`, `succeeded`, `failed` | integer | Keywords finished, and how they ended. |
| `createdAt`, `deadlineAt`, `completedAt` | integer \| null | Milliseconds since 1970 (UTC). `completedAt` is `null` while running. |
| `delivery` | string | The deadline tier. |
| `keywordCount`, `workUnits` | integer | What the job counts against your daily keywords. |

You don't need to wait for `completed`: [Get suggest job results](/docs/suggest/get-results) returns keywords as they finish.

## Errors

| Status | When |
|---|---|
| 401 | No valid API key. |
| 404 | No job with this id for this key. |


---

# Get suggest job results
Source: https://rankfield.dev/docs/suggest/get-results

Read a suggest job's keywords as they finish, each with its engine answer, and page through them with a cursor.

`GET https://rankfield.dev/v1/bing/suggest/jobs/{id}/results`

```bash cURL
curl 'https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a/results?cursor=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a/results?cursor=0",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a/results?cursor=0", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "id": "1e3aff33-2831-4112-b934-cb727ab6c23a",
  "status": "completed",
  "total": 2,
  "completed": 2,
  "succeeded": 2,
  "failed": 0,
  "createdAt": 1792938856915,
  "deadlineAt": 1792938916915,
  "completedAt": 1792938857066,
  "delivery": "priority",
  "keywordCount": 2,
  "workUnits": 2,
  "cursor": 2,
  "hasMore": false,
  "items": [
    {
      "index": 0,
      "query": "keyword research",
      "market": "en-US",
      "status": 200,
      "result": {
        "source": "bing-suggest",
        "query": "keyword research",
        "market": "en-US",
        "count": 17,
        "suggestions": ["keyword research", "keyword research tool", "keyword research tool free"]
      },
      "attempts": 1,
      "cache": "hit",
      "ageSeconds": 17,
      "durationMs": 0
    }
  ]
}
```

## 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 from [Start a suggest job](/docs/suggest/start-a-job). |

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `cursor` | integer | No | `0` | Where to continue: the `cursor` of the previous answer. |
| `limit` | integer | No | `100` | Items per answer, 1–500. |

## Read results

Start with `cursor=0`. Read `items`, then ask again with the returned `cursor` until `status` is no longer `running` and `hasMore` is `false`. Items arrive in the order they finish; `index` is the keyword's position in your `queries`, from 0.

| Field | Type | Description |
|---|---|---|
| `items[].index` | integer | Position in `queries`. |
| `items[].query`, `market` | string | The keyword and market. |
| `items[].status` | integer | `200`, or the error status for this keyword: `499` after a cancel, `504` when it was not finished by the deadline. |
| `items[].result` | object | The same answer as the single-keyword GET. |
| `items[].attempts` | integer | Tries it took. |
| `items[].cache`, `ageSeconds` | string, integer | Whether a stored answer was used, and its age. |
| `cursor` | integer | Where to continue. |
| `hasMore` | boolean | Whether more finished items are ready to read now. While the job runs and you have caught up, it is `false`. |

## Errors

| Status | When |
|---|---|
| 400 | `cursor` or `limit` is invalid. |
| 401 | No valid API key. |
| 404 | No job with this id for this key. |

## MCP

On the [MCP server](/docs/agents/mcp-server), the tools for this are `get_bing_suggest_results`, `get_duckduckgo_suggest_results` and `get_yahoo_search_predictions_results`.


---

# Cancel a suggest job
Source: https://rankfield.dev/docs/suggest/cancel-a-job

Stop a running suggest job. Keywords already finished stay readable; the rest end with status 499.

`POST https://rankfield.dev/v1/bing/suggest/jobs/{id}/cancel`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a/cancel",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a/cancel", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "id": "1e3aff33-2831-4112-b934-cb727ab6c23a",
  "status": "cancelled",
  "total": 2,
  "completed": 2,
  "succeeded": 1,
  "failed": 1,
  "createdAt": 1792938856915,
  "deadlineAt": 1792938916915,
  "completedAt": 1792938857066,
  "delivery": "priority",
  "keywordCount": 2,
  "workUnits": 2
}
```

## 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 from [Start a suggest job](/docs/suggest/start-a-job). |

## Response

The job, as in [Get a suggest job](/docs/suggest/get-a-job). A job that has already finished is returned unchanged.

## Errors

| Status | When |
|---|---|
| 401 | No valid API key. |
| 404 | No job with this id for this key. |


---

# Get usage and capacity
Source: https://rankfield.dev/docs/suggest/get-usage-and-capacity

See how many keywords your key has used today on a suggest engine, its jobs and requests by status, and the engine's delivery tiers.

`GET https://rankfield.dev/v1/bing/suggest/usage`

```bash cURL
curl 'https://rankfield.dev/v1/bing/suggest/usage' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/bing/suggest/usage",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bing/suggest/usage", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "day": "2026-10-26",
  "admittedKeywords": 10240,
  "limits": "off",
  "jobs": [{ "status": "completed", "jobs": 5, "keywords": 10120, "succeeded": 10120 }],
  "live": [{ "status": 200, "requests": 120 }]
}
```

Each engine has its own `/usage` and `/capacity`: `{base path}/usage`, `{base path}/capacity`.

## Usage

| Field | Type | Description |
|---|---|---|
| `day` | string | The UTC day the counts cover. |
| `admittedKeywords` | integer | Keywords used today. |
| `limits` | string | `off`: no per-key limits for now. |
| `jobs` | array | Every job this key has started on this engine, counted by status: `{status, jobs, keywords, succeeded}`. |
| `live` | array | Single-keyword requests by status, `{status, requests}`, counted since the key first used this engine (not reset daily). Requests still in flight come first, with `status: null`. |

## Capacity

`GET {base path}/capacity` describes the engine: `"limits": "off"` (no per-key limits), and `deliveryTiers` with each tier's target (`live` 6 s, `priority` 60 s, `standard` 300 s). Targets are design values, not a measured guarantee.


---

# Link Extraction
Source: https://rankfield.dev/docs/link-extraction

Extract every link on a live web page, with anchor text and rel values, for one page at a time or up to 600 pages in a job.

Fetch a public page live and list its links: the target URL, the anchor text, the `rel` values (nofollow, sponsored, ugc), whether each link is internal or external, and how often it appears.

Use [Extract links from a page](/docs/link-extraction/extract-links) for one page, or a job for up to 600 pages at once.

## Pages

- [Extract links from a page](/docs/link-extraction/extract-links): Fetch a live web page and list every link on it: URL, anchor text, rel values, internal or external, and how often it appears.
- [Start a Link Extraction job](/docs/link-extraction/start-a-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.
- [Get a Link Extraction job](/docs/link-extraction/get-a-job): Check a Link Extraction job: its status, how many pages are done, succeeded and failed, and its progress from 0 to 1.
- [Get Link Extraction results](/docs/link-extraction/get-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.
:::


---

# Extract links from a page
Source: https://rankfield.dev/docs/link-extraction/extract-links

Fetch a live web page and list every link on it: URL, anchor text, rel values, internal or external, and how often it appears.

`GET https://rankfield.dev/v1/html/link-extraction?url={url}`

```bash cURL
curl 'https://rankfield.dev/v1/html/link-extraction?url=https://www.iana.org/help/example-domains' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/html/link-extraction?url=https://www.iana.org/help/example-domains",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/html/link-extraction?url=https://www.iana.org/help/example-domains", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "url": "https://www.iana.org/help/example-domains",
  "finalUrl": "https://www.iana.org/help/example-domains",
  "status": 200,
  "title": "Example Domains",
  "redirects": [],
  "collectedAt": "2026-10-25T14:34:22.639Z",
  "cached": false,
  "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
    },
    {
      "href": "https://www.iana.org/domains",
      "anchor": "Domains",
      "internal": true,
      "rel": [],
      "nofollow": false,
      "sponsored": false,
      "ugc": false,
      "occurrences": 2
    }
  ],
  "view": "unique",
  "jobId": "01a1737b-85c9-781b-a66f-03241b7c96fd"
}
```

```json 202
{
  "id": "01a1737c-067c-738f-a990-07518fe64d5e",
  "status": "running",
  "url": "https://www.iana.org/help/example-domains",
  "message": "The page is still being collected; read it from resultsUrl.",
  "statusUrl": "/v1/html/link-extraction/jobs/01a1737c-067c-738f-a990-07518fe64d5e",
  "resultsUrl": "/v1/html/link-extraction/jobs/01a1737c-067c-738f-a990-07518fe64d5e/results",
  "retryAfterMs": 2000
}
```

```json 401
{
  "error": {
    "message": "A valid API key is required"
  }
}
```

The page is fetched live, as plain HTML without running JavaScript, and the answer usually arrives within a few seconds. For many pages, [start a job](/docs/link-extraction/start-a-job).

## Parameters

### Headers

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

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `url` | string | Yes | – | A public page. `http://` is upgraded to HTTPS and a URL without a scheme gets `https://`. Credentials, custom ports and private hosts are refused. |
| `view` | string | No | `unique` | `unique`: one entry per distinct target, with `occurrences`. `occurrences`: one entry per link, in page order. |
| `type` | string | No | `all` | `all`, `internal` (same hostname as the final URL) or `external`. `counts` always cover the whole page. |
| `maxAge` | integer | No | `60` | Seconds, 0–3,600. A copy of the page fetched at most this long ago may be reused (`cached: true`). `0` always fetches. |
| `wait` | integer | No | `60` | Seconds to wait for the page, 1–85. If it is not ready by then, the answer is `202` with `resultsUrl`. |

## Response

| Field | Type | Description |
|---|---|---|
| `url` | string | The URL you sent, after normalising. |
| `finalUrl` | string | The page that answered, after redirects. |
| `status` | integer | The website's HTTP status. |
| `title` | string \| null | The page title. |
| `redirects` | array | Each redirect on the way, `{url, status}`. |
| `collectedAt` | string | When the page was fetched (UTC). |
| `cached` | boolean | `true` when a copy within `maxAge` was reused. |
| `counts` | object | `links` (distinct targets), `internal`, `external` and `occurrences`, for the whole page. |
| `links[].href` | string | The absolute target URL. |
| `links[].anchor` | string | The link text (or the image's alt text). |
| `links[].internal` | boolean | Same hostname as `finalUrl`. |
| `links[].rel` | string[] | The `rel` values. |
| `links[].nofollow`, `sponsored`, `ugc` | boolean | Whether `rel` holds each value. |
| `links[].occurrences` | integer | How many times the target appears (with `view=unique`). |
| `view` | string | The view used. |
| `jobId` | string | The one-page job behind the request. |

## Common questions

### Why are there no links, or fewer than in my browser?

The page is read as served, without JavaScript. Links that a script adds after loading are not in the HTML. [Bot View](/docs/bot-view/check-a-page) tells you whether a page needs JavaScript.

### How is internal decided?

By hostname: `www.example.com` and `blog.example.com` are different hosts. Links to other subdomains count as external.

## Errors

| Status | When |
|---|---|
| 202 | The page is not ready within `wait`. Read it from `resultsUrl` (see [Get results](/docs/link-extraction/get-results)). |
| 400 | `url` or another parameter is missing or invalid. |
| 401 | No valid API key. |
| 422 | The website answered with an error, timed out, or the page could not be read. The body has the page's `status` and an `error` with `message`, `code` (such as `SOURCE_HTTP_404`) and `retryable`. |
| 429 | The service is busy. Wait for `Retry-After`. |
| 503 | The service is busy or paused. Retry after `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 `extract_page_links`.


---

# Start a Link Extraction job
Source: https://rankfield.dev/docs/link-extraction/start-a-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`.


---

# Get a Link Extraction job
Source: https://rankfield.dev/docs/link-extraction/get-a-job

Check a Link Extraction job: its status, how many pages are done, succeeded and failed, and its progress from 0 to 1.

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

```bash cURL
curl 'https://rankfield.dev/v1/html/link-extraction/jobs/01a1737c-067c-738f-a990-07518fe64d5e' \
  -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",
    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", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "id": "01a1737c-067c-738f-a990-07518fe64d5e",
  "status": "completed",
  "total": 2,
  "completed": 2,
  "succeeded": 2,
  "failed": 0,
  "progress": 1,
  "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"
}
```

## 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 from [Start a Link Extraction job](/docs/link-extraction/start-a-job). |

## Response

| Field | Type | Description |
|---|---|---|
| `status` | string | `queued`, `running` or `completed`. |
| `total` | integer | URLs in the job. |
| `completed` | integer | Pages finished, whether they succeeded or failed. |
| `succeeded`, `failed` | integer | How the finished pages ended. |
| `progress` | number | `completed / total`, from 0 to 1. |
| `createdAt`, `deadlineAt`, `expiresAt` | string | When it started, its delivery deadline, and when it is deleted. |

You don't need to wait for `completed`: [Get Link Extraction results](/docs/link-extraction/get-results) returns each page as soon as it finishes.

## Errors

| Status | When |
|---|---|
| 401 | No valid API key. |
| 404 | No job with this id for this key. |
| 410 | The job has expired: jobs are kept for 24 hours after they are created. |


---

# Get Link Extraction results
Source: https://rankfield.dev/docs/link-extraction/get-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`.


---

# Scrape
Source: https://rankfield.dev/docs/scrape

Turn any public web page into clean Markdown for LLMs, with its metadata, links, images, structured data and AI-use signals.

Scrape reads one page as plain HTML, the way AI crawlers see it, and returns it as Markdown (the whole page as a person reads it, or only the article with `scope=main`) together with everything else on the page that a model or an SEO check needs. One call for one page, or a job for up to 10,000.

## Pages

- [Scrape a page](/docs/scrape/scrape-a-page): Turn a web page into clean Markdown for LLMs, with its metadata, headings, links, images, structured data, language and AI-use signals.
- [Start a Scrape job](/docs/scrape/start-a-job): Scrape up to 10,000 URLs in one background job; each item takes the same parameters as a single call.
- [Get a Scrape job](/docs/scrape/get-a-job): Check a Scrape job: its status, how many items are done and failed, and when its results expire.
- [Get Scrape job results](/docs/scrape/get-results): Read a Scrape job's items as each one finishes, with its full answer or error, and page through them with a cursor.
- [Cancel a Scrape job](/docs/scrape/cancel-a-job): Stop a Scrape job. Items already finished stay readable for 24 hours; items not started are dropped.
:::


---

# Scrape a page
Source: https://rankfield.dev/docs/scrape/scrape-a-page

Turn a web page into clean Markdown for LLMs, with its metadata, headings, links, images, structured data, language and AI-use signals.

`GET https://rankfield.dev/v1/scrape?url={url}`

```bash cURL
curl 'https://rankfield.dev/v1/scrape?url=https://rankfield.dev/blog/what-is-site-strength' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/scrape?url=https://rankfield.dev/blog/what-is-site-strength",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/scrape?url=https://rankfield.dev/blog/what-is-site-strength", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "url": "https://rankfield.dev/blog/what-is-site-strength",
  "finalUrl": "https://rankfield.dev/blog/what-is-site-strength",
  "status": 200,
  "redirects": [],
  "contentType": "text/html; charset=utf-8",
  "bytes": 27716,
  "truncated": false,
  "fetchedAt": "2026-10-26T18:52:46Z",
  "timing": {
    "dnsMs": 0.0,
    "connectMs": 0.0,
    "tlsMs": 0.0,
    "firstByteMs": 42.9,
    "totalMs": 43.2
  },
  "language": {
    "code": "en",
    "script": "Latn",
    "confidence": 1,
    "source": "content",
    "declared": {
      "code": "en",
      "region": null,
      "script": null,
      "htmlLang": "en",
      "contentLanguage": null,
      "metaContentLanguage": null,
      "ogLocale": null
    },
    "detected": {
      "code": "en",
      "iso639_3": "eng",
      "name": "English",
      "script": "Latn",
      "confidence": 1,
      "reliable": true
    },
    "agree": true,
    "textLetters": 837
  },
  "metadata": {
    "title": "What is Site Strength? — Rankfield",
    "description": "Another SEO score? Here is what ours tells you, the evidence behind it, and how 20 real domains compare.",
    "canonical": null,
    "robots": null,
    "xRobotsTag": null,
    "hreflang": [],
    "siteName": null,
    "author": null,
    "publishedTime": null,
    "favicon": null,
    "ogImage": null,
    "charset": "utf-8"
  },
  "headings": [
    {
      "level": 1,
      "text": "What is Site Strength?"
    },
    {
      "level": 2,
      "text": "How we build Site Strength"
    },
    {
      "level": 2,
      "text": "Okay, enough science. How do the numbers compare?"
    }
  ],
  "content": {
    "mode": "page",
    "extraction": "document",
    "words": 854,
    "truncated": false,
    "markdown": "[← All articles](https://rankfield.dev/blog)  \nTHE SCORE\n\n# What is Site Strength?\n\nAnother SEO score? Here is what ours tells you, the evidence behind it, and how 20 real domains compare.\n\nSite Strength is our 0–100 estimate of a website's link strength. It looks at how many different websites link to a domain and how much weight those links carry. Use it to decide which competitors or link prosp …"
  },
  "links": [
    {
      "url": "https://rankfield.dev/",
      "text": "Rankfield",
      "rel": [],
      "internal": true,
      "nofollow": false,
      "sponsored": false,
      "ugc": false,
      "occurrences": 3
    },
    {
      "url": "https://rankfield.dev/endpoints/",
      "text": "Endpoints",
      "rel": [],
      "internal": true,
      "nofollow": false,
      "sponsored": false,
      "ugc": false,
      "occurrences": 1
    },
    {
      "url": "https://rankfield.dev/free-seo-tools/site-strength",
      "text": "Free tools",
      "rel": [],
      "internal": true,
      "nofollow": false,
      "sponsored": false,
      "ugc": false,
      "occurrences": 1
    }
  ],
  "images": [
    {
      "src": "https://rankfield.dev/images/site-strength-links.webp",
      "alt": "Illustrated websites sending links toward one domain",
      "width": 1672,
      "height": 941,
      "lazy": false,
      "srcset": []
    }
  ],
  "structuredData": {
    "jsonLd": [],
    "microdata": [],
    "openGraph": {},
    "twitter": {}
  },
  "signals": {
    "noai": false,
    "noimageai": false,
    "tdmReserved": null,
    "tdmPolicy": null,
    "tdmSource": null
  },
  "blocked": null,
  "cached": false,
  "ageSeconds": 0
}
```

```json 401
{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required"
  }
}
```

We fetch the page once, as plain HTML: what AI crawlers such as GPTBot and ClaudeBot see. When that HTML is an empty JavaScript app shell, we render the page and read it as a browser shows it; `render=never` keeps the raw HTML only, and `render=always` renders every page.

Send the parameters as a query string with `GET`, or as a JSON object (up to 1 MB) with `POST` to the same path. For many URLs, [start a job](/docs/scrape/start-a-job).

## Parameters

### Headers

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

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `url` | string | Yes | – | A public `http` or `https` URL. Without a scheme, `https://` is added. |
| `scope` | string | No | `page` | How much of the page the Markdown covers. `page`: the whole page in reading order, each section once, collapsed content included, without the site's menus and link lists (navigation, header and footer links, sidebars, category and archive lists, language and currency pickers, share and follow buttons), skip links and cookie banners; contact details such as an e-mail address or a phone number stay. `main`: the main article only, or the page's content when the article found is very short next to the rest of the page. `all`: everything, menus and footers included, each section still once. |
| `include` | string | No | `all parts` | Only these parts, comma-separated: `content`, `links`, `images`, `headings`, `metadata`, `structuredData`, `language`, `signals`, `highlights`. Parts left out come back as `null`. `highlights` alone returns just the passages, and needs `query`. |
| `query` | string | No | – | Words to look for, 1–300 characters. Adds `highlights`: the page's passages that best match them, best first. Close forms count ("price" finds "prices"), synonyms don't; put a phrase in double quotes to match it as a phrase. The same page and query always give the same passages. |
| `maxPassages` | integer | No | `5` | 1–20: the most passages `highlights` holds. Only with `query`: without it, `400`. |
| `passageChars` | integer | No | `600` | 200–2,000: about how long each passage is, in characters. Only with `query`: without it, `400`. |
| `render` | string | No | `auto` | `auto` runs the page's JavaScript only when its raw HTML is an empty app shell; `never` returns the raw HTML only, as AI crawlers see it; `always` runs it every time. See [Rendered pages](#rendered-pages). |
| `screenshot` | string | No | – | `viewport` or `fullPage`: also return a WebP image of the page as a browser shows it, the first screen or the whole page up to 12,000 px tall. |
| `viewport` | string | No | `mobile` | `mobile` or `desktop`: the screen size for rendering and screenshots. Mobile is 412×915, like Google's smartphone crawler; desktop is 1366×768. |
| `maxAge` | integer | No | `600` | How old a stored answer may be, in seconds, up to 2,592,000 (30 days). `0` fetches fresh. |
| `timeout` | integer | No | `20` | How long the call may take, in seconds, 1–60. |

## Response

| Field | Type | Description |
|---|---|---|
| `url` | string | The page you asked for. |
| `finalUrl` | string | The page that answered, after redirects. |
| `status` | integer | The website's HTTP status. A 404 or 500 from the website is reported here, not as an error. |
| `redirects` | array | Each redirect, `{url, status}`. |
| `contentType`, `bytes` | string, integer | The page's Content-Type and size. |
| `truncated` | boolean | `true` when the page was over 10 MB or its Markdown over 1 MB, and the first part was kept. |
| `fetchedAt` | string | When the page was fetched (UTC). |
| `timing` | object | Milliseconds for DNS, connecting, TLS, the first byte and the whole fetch. |
| `language` | object | `code` (such as `en`; `null` when unknown), `script`, `confidence` (0–1), `source` (`content`: read from the text, `declared`: from the markup, or `none`), `declared` (what the markup says: `<html lang>`, `Content-Language`, the meta tag, `og:locale`) and `detected` (the reading of the text alone). |
| `metadata` | object | Title, description, canonical, meta robots, X-Robots-Tag, hreflang, site name, author, published time, favicon, og:image and charset. |
| `headings` | array | The H1–H6 outline in page order, `{level, text}`. |
| `content` | object | `markdown`, `words`, `mode` (the scope used: `page`, `main` or `all`), `extraction` (`article` when `main` found an article, `document` for the whole page, `text` for a plain-text or Markdown body passed through, or `pdf` for a PDF's text) and `truncated`. A product page whose text doesn't name the product starts with the product's name, description and price from the page's structured data. |
| `highlights` | array \| null | Only with `query`: the passages that best match it, best first, each `{text, heading, offset, score, matched}`: the passage as plain text, the headings above it (such as `Acme widgets › Pricing`, or `null`), where it starts in `content.markdown` (in characters), its score, and the query words found in it. `[]` when nothing matches; `null` when the page is blocked or isn't text. |
| `links` | array | Every link once, in page order: `url`, `text`, `rel`, `internal`, `nofollow`, `sponsored`, `ugc`, `occurrences`. |
| `images` | array | Every image once: `src`, `alt`, `width`, `height`, `srcset`, and `lazy` when the URL only sits in a lazy-loading attribute. |
| `structuredData` | object | `jsonLd` (parsed), `microdata`, `openGraph` and `twitter`. |
| `signals` | object | AI-use signals: `noai`, `noimageai`, and the TDM reservation (`tdmReserved`, `tdmPolicy`, `tdmSource`). |
| `render` | object | `{mode, rendered, reason, tier, ms, timedOut, requests, robotsBlocked}`, or `unavailable` saying why the page wasn't rendered (the answer is then the raw-HTML one). |
| `screenshot` | object | With `screenshot`: `{format: "webp", kind, viewport, bytes, data}`, the image in base64. |
| `blocked` | object \| null | `{by, kind}` when a firewall answered instead of the page, such as a "verify you're human" challenge. It is reported as it came, never rendered or solved. |
| `cached`, `ageSeconds` | boolean, integer | Whether this answer came from our store, and how old it is. |

## Rendered pages

When Scrape renders a page (an empty app shell under the default `render=auto`, or every page with `render=always`), it loads the page in Chrome, runs its JavaScript and builds every part of the answer from the page as a browser shows it: content, links, metadata, highlights. `render.rendered` says whether it ran, and `render.reason` says why or why not. When the rendering lane is busy, the page can't be rendered in time, or the site's robots.txt asks for a Crawl-delay of a second or more (`crawlDelay`), you get the raw-HTML answer with `render.unavailable` saying why.

Rendering follows the same rules as every Rankfield fetch:

- robots.txt for every script and file the page loads (the ones it keeps out are listed in `render.robotsBlocked`);
- no cookies and no form posts;
- images, media, fonts and trackers are not loaded unless you ask for a screenshot.

A page behind a bot challenge is reported as blocked, never worked around.

## PDF documents

A PDF (`application/pdf`, or an untyped file that starts as a PDF) is read as a document:

- **Content:** the document's text as `content.markdown` (`extraction: "pdf"`), the same for every `scope`, plus `content.pdf`: `pages`, `pagesRead` and `stopped`.
- **Length:** up to the first 300 pages and 10 MB are read. When the text ends early, `stopped` says why (`sizeLimit`, `pageLimit`, `timeLimit`, `textLimit`) and `content.truncated` is true.
- **Metadata:** the document's title (or its first line), author, subject as `description`, creation date as `publishedTime`.
- Links, images, headings and structured data are empty.

A PDF we can't read is a `415` `unsupported_content_type` with `details.reason`: `noTextLayer` (scanned pages, no text), `encrypted` (needs a password), `damaged` or `tooComplex`. Any other type (images, JSON, XML…) on a 2xx is a `415` with `details.contentType`.

## How we fetch

We fetch as `Rankfield-User` (`Mozilla/5.0 (compatible; Rankfield-User/1.0; +https://rankfield.dev/bot)`).

Scrape reads the raw HTML first. When that HTML is an empty JavaScript app shell, it renders the page in Chrome and answers from what a browser shows (`render.rendered` true). Pages with their content in the HTML are answered from the HTML, as before. Ask `render=never` for the raw HTML only.

- **robots.txt:** obeyed on every request and redirect, following the rules for `Rankfield-User`, or for `RankfieldBot` when the file has none for it, or `*` when it has neither. A page it disallows is refused and never fetched.
- **Firewalls:** a challenge, CAPTCHA or block page is reported in the answer, never worked around and never retried.
- **Never:** cookies, logins, proxies or other bots' names.
- **Excluded sites:** Reddit, LinkedIn, Facebook, Instagram, X/Twitter and TikTok (subdomains included), Google search result pages, and sites whose owners asked us are never fetched.
- **Pace:** each website is fetched gently, shared by all customers, slower when its robots.txt sets a `Crawl-delay` or after a slow answer. Many URLs on one site go at that site's pace.

Repeat calls to the same website within about a minute can wait their turn for that site's slot. If the wait runs past the call's time limit (20 seconds by default), the call ends with `504` `timeout` and `details.reason` `sitePace`. It doesn't count as usage: retry after `Retry-After`, or allow a longer `timeout`.

More: [Rankfield crawlers](/bot).

## Errors

Errors are `{"error": {"code", "message", "details"}}`. Branch on `code`; `message` is for people.

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | A parameter is missing, unknown or malformed. |
| 401 | `unauthorized` | No valid API key. |
| 403 | `robots_disallowed` | robots.txt disallows Rankfield-User for the page or a redirect; `details` has the rule and line. |
| 403 | `site_excluded` | The site is on the exclusion list. |
| 403 | `blocked` | The website's bot protection refused us. Reported at once and never worked around; `details` says which protection. Not counted as usage. |
| 415 | `unsupported_content_type` | A page that answered 2xx isn't HTML, plain text, markdown or a readable PDF (an image, JSON, a scanned or password-protected PDF…). `details.reason` says why for PDFs. A website's error page in another type is an answer, not a 415. |
| 422 | `address_not_public` | The host resolves to a private or internal address. |
| 429 | `busy` | Our fetch capacity is busy: the call was refused at once, waited 4 seconds without a turn, or its time limit ran out while it waited (then `details.reason` is `capacity`). Not counted as usage. Retry after `Retry-After` seconds. |
| 500 | `internal` | Our bug. Retry. |
| 502 | `fetch_failed` | The website could not be reached (DNS, connection, TLS, more than 5 redirects); `details.reason` says which. |
| 503 | `unavailable` | The service is restarting or briefly unavailable. Retry after `Retry-After`. (A full fetch capacity answers `429` `busy`.) |
| 504 | `timeout` | The website didn't answer within the call's time limit. When `details.reason` is `sitePace`, the call waited its turn for this website instead, which we fetch gently, shared by all customers: retry after `Retry-After`, or allow a longer `timeout`. |

Only answered pages and the `415`, `502` and website-side `504` errors count as usage; refusals, our own errors (`500`, `503`), `429` `busy` and a `504` with `details.reason` `sitePace` don't.

## Limits

No per-key limits. When the server is busy you get `429` `busy` with `Retry-After`. Waiting calls are served in turn across keys, so a key with a few calls is never stuck behind one with thousands.

## MCP

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


---

# Start a Scrape job
Source: https://rankfield.dev/docs/scrape/start-a-job

Scrape up to 10,000 URLs in one background job; each item takes the same parameters as a single call.

`POST https://rankfield.dev/v1/scrape/jobs`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/scrape/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: scrape-2026-10-26' \
  -d '{"items":[{"url":"https://rankfield.dev/blog/what-is-site-strength"},{"url":"https://example.com/"}]}'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/scrape/jobs",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": "scrape-2026-10-26"},
    json={"items": [{"url": "https://rankfield.dev/blog/what-is-site-strength"}, {"url": "https://example.com/"}]},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/scrape/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "scrape-2026-10-26",
  },
  body: JSON.stringify({"items":[{"url":"https://rankfield.dev/blog/what-is-site-strength"},{"url":"https://example.com/"}]}),
});
console.log(await response.json());
```

```json 202
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "queued",
    "total": 2,
    "done": 0,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": null,
    "expiresAt": null
  }
}
```

```json 409
{
  "error": {
    "code": "invalid_input",
    "message": "This Idempotency-Key was used for different items"
  }
}
```

## 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 | Yes | – | 1–200 characters you choose for this job. Sending the same key with the same body again returns the same job instead of a new one. |

### Body

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `items` | object[] | Yes | – | 1–10,000 items. Each takes the same parameters as [Scrape a page](/docs/scrape/scrape-a-page), as a JSON object. |

Every item is checked before the job starts. If any is invalid, the whole request is a `400` listing the first 20 (`index` and `message`).

## Response

`202` with `job`. A byte-identical body with the same `Idempotency-Key` replays the job (`200`, `Idempotency-Replayed: true`); any other body with that key is `409`.

| Field | Type | Description |
|---|---|---|
| `job.id` | string | The job id. |
| `job.status` | string | `queued`, `running`, `done` or `canceled`. |
| `job.total` | integer | URLs in the job. |
| `job.done` | integer | Items that succeeded. |
| `job.failed` | integer | Items that failed. |
| `job.createdAt`, `job.finishedAt` | string \| null | When it was created and when it finished (UTC). |
| `job.expiresAt` | string \| null | When its results are deleted: 24 hours after it finishes. |

A job runs 16 items at a time. An item counts as usage once the job accepts it, whatever its outcome. Items use the endpoint's default `timeout` rather than their own, and retry `busy` by themselves (up to 10 times). Follow it with [Get a Scrape job](/docs/scrape/get-a-job) and read items with [Get Scrape job results](/docs/scrape/get-results).

## Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | No `Idempotency-Key`, no items, too many items, or an invalid item. |
| 401 | `unauthorized` | No valid API key. |
| 409 | `invalid_input` | The `Idempotency-Key` was used before with a different body. |
| 429 | `busy` | The batch queue is full: 200,000 items from all keys are already waiting. Retry after `Retry-After` (60 seconds). |
| 503 | `unavailable` | Batch jobs are paused (storage). Retry after `Retry-After` (300 seconds). |

## Limits

Send up to 10,000 URLs in one job, and as many jobs as you like. No per-key limits. Jobs from all keys share one queue: when 200,000 items are already waiting, a new job answers `429` `busy` with `Retry-After` (60 seconds).

## MCP

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


---

# Get a Scrape job
Source: https://rankfield.dev/docs/scrape/get-a-job

Check a Scrape job: its status, how many items are done and failed, and when its results expire.

`GET https://rankfield.dev/v1/scrape/jobs/{id}`

```bash cURL
curl 'https://rankfield.dev/v1/scrape/jobs/8f14e45fceea167a5a36dedd4bea2543' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/scrape/jobs/8f14e45fceea167a5a36dedd4bea2543",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/scrape/jobs/8f14e45fceea167a5a36dedd4bea2543", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "running",
    "total": 2,
    "done": 1,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": null,
    "expiresAt": null
  }
}
```

## 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 from [Start a Scrape job](/docs/scrape/start-a-job). |

## Response

| Field | Type | Description |
|---|---|---|
| `job.id` | string | The job id. |
| `job.status` | string | `queued`, `running`, `done` or `canceled`. |
| `job.total` | integer | URLs in the job. |
| `job.done` | integer | Items that succeeded. |
| `job.failed` | integer | Items that failed. |
| `job.createdAt`, `job.finishedAt` | string \| null | When it was created and when it finished (UTC). |
| `job.expiresAt` | string \| null | When its results are deleted: 24 hours after it finishes. |

Only the key that started a job can read it; any other key gets `404`.

## Errors

| Status | Code | When |
|---|---|---|
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |


---

# Get Scrape job results
Source: https://rankfield.dev/docs/scrape/get-results

Read a Scrape job's items as each one finishes, with its full answer or error, and page through them with a cursor.

`GET https://rankfield.dev/v1/scrape/jobs/{id}/results`

```bash cURL
curl 'https://rankfield.dev/v1/scrape/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/scrape/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/scrape/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "done",
    "total": 2,
    "done": 1,
    "failed": 1,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": "2026-10-26T18:00:04Z",
    "expiresAt": "2026-10-27T18:00:04Z"
  },
  "cursor": "2",
  "hasMore": false,
  "items": [
    { "index": 0, "ok": true, "result": { "…": "the same answer as a single call" } },
    { "index": 1, "ok": false, "error": { "code": "fetch_failed", "message": "…", "details": { "reason": "dns" } } }
  ]
}
```

## 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 from [Start a Scrape job](/docs/scrape/start-a-job). |

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `cursor` | integer | No | `0` | Where to continue: the `cursor` of the previous answer (returned as a string; send it back as it is). |
| `limit` | integer | No | `100` | Items per answer, 1–500. |

## Read results

Start with `cursor=0`. Read `items`, then ask again with the returned `cursor` while `hasMore` is `true`. Items arrive in the order they finish; `index` is the item's position in your `items`, from 0.

| Field | Type | Description |
|---|---|---|
| `job` | object | The job, as in [Get a Scrape job](/docs/scrape/get-a-job). |
| `items[].index` | integer | Position in your `items`. |
| `items[].ok` | boolean | Whether the item succeeded. |
| `items[].result` | object | The same answer as [Scrape a page](/docs/scrape/scrape-a-page). |
| `items[].error` | object | `{code, message, details}`, as a single call's error. |
| `cursor` | string | Pass it back to continue. |
| `hasMore` | boolean | Whether more items exist now or will. |

## Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | `cursor` or `limit` is invalid. |
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |

## MCP

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


---

# Cancel a Scrape job
Source: https://rankfield.dev/docs/scrape/cancel-a-job

Stop a Scrape job. Items already finished stay readable for 24 hours; items not started are dropped.

`POST https://rankfield.dev/v1/scrape/jobs/{id}/cancel`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/scrape/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/scrape/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/scrape/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "canceled",
    "total": 2,
    "done": 1,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": "2026-10-26T18:00:04Z",
    "expiresAt": "2026-10-27T18:00:04Z"
  }
}
```

## 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 from [Start a Scrape job](/docs/scrape/start-a-job). |

## Response

The job, now `canceled`, as in [Get a Scrape job](/docs/scrape/get-a-job). Items already running finish; nothing new starts. A job that has already finished is returned unchanged (its status stays `done`).

## Errors

| Status | Code | When |
|---|---|---|
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |


---

# Bot View
Source: https://rankfield.dev/docs/bot-view

See how 274 search engines, AI crawlers and SEO tools are treated by a page's robots.txt, llms.txt, meta robots and TDM signals.

Bot View answers "which bots can read this page?" for every known crawler at once, with the robots.txt rule and line behind each verdict, and checks the other signals sites use for crawlers and AI: llms.txt, meta robots, X-Robots-Tag, Content-Signal and TDMRep.

## Pages

- [Check how crawlers see a page](/docs/bot-view/check-a-page): See which of 274 search, AI and SEO crawlers a page's robots.txt allows, with the deciding rule, plus llms.txt, meta robots and TDM signals.
- [Start a Bot View job](/docs/bot-view/start-a-job): Check up to 10,000 URLs with Bot View in one background job; each item takes the same parameters as a single call.
- [Get a Bot View job](/docs/bot-view/get-a-job): Check a Bot View job: its status, how many items are done and failed, and when its results expire.
- [Get Bot View job results](/docs/bot-view/get-results): Read a Bot View job's items as each one finishes, with its full answer or error, and page through them with a cursor.
- [Cancel a Bot View job](/docs/bot-view/cancel-a-job): Stop a Bot View job. Items already finished stay readable for 24 hours; items not started are dropped.
:::


---

# Check how crawlers see a page
Source: https://rankfield.dev/docs/bot-view/check-a-page

See which of 274 search, AI and SEO crawlers a page's robots.txt allows, with the deciding rule, plus llms.txt, meta robots and TDM signals.

`GET https://rankfield.dev/v1/bot-view?url={url}`

```bash cURL
curl 'https://rankfield.dev/v1/bot-view?url=https://www.airbnb.com/' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/bot-view?url=https://www.airbnb.com/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bot-view?url=https://www.airbnb.com/", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "url": "https://www.airbnb.com/",
  "agents": [
    "all"
  ],
  "finalUrl": "https://www.airbnb.com/",
  "status": 200,
  "redirects": [],
  "summary": {
    "agents": 274,
    "allowed": 265,
    "blocked": 9,
    "blockedSite": 9,
    "purposes": {
      "aiTraining": {
        "agents": 44,
        "allowed": 38,
        "blocked": 6,
        "blockedSite": 6
      },
      "aiSearch": {
        "agents": 30,
        "allowed": 30,
        "blocked": 0,
        "blockedSite": 0
      },
      "search": {
        "agents": 29,
        "allowed": 29,
        "blocked": 0,
        "blockedSite": 0
      }
    },
    "robotsTxt": "found",
    "pageChecked": true
  },
  "companies": [
    {
      "company": "OpenAI",
      "agents": [
        {
          "token": "GPTBot",
          "matchedAs": "GPTBot",
          "purpose": "aiTraining",
          "controlToken": false,
          "respectsRobots": "yes",
          "known": true,
          "allowed": false,
          "page": {
            "allowed": false,
            "group": "GPTBot",
            "groupKind": "named",
            "rule": "Disallow: /",
            "line": 691,
            "note": null
          },
          "site": {
            "allowed": false,
            "group": "GPTBot",
            "groupKind": "named",
            "rule": "Disallow: /",
            "line": 691,
            "note": null
          },
          "finalUrl": null,
          "crawlDelay": null,
          "directives": [],
          "docs": "https://developers.openai.com/api/docs/bots",
          "note": null
        },
        {
          "token": "OAI-SearchBot",
          "matchedAs": "OAI-SearchBot",
          "purpose": "aiSearch",
          "controlToken": false,
          "respectsRobots": "yes",
          "known": true,
          "allowed": true,
          "page": {
            "allowed": true,
            "group": "OAI-SearchBot",
            "groupKind": "named",
            "rule": null,
            "line": null,
            "note": null
          },
          "site": {
            "allowed": true,
            "group": "OAI-SearchBot",
            "groupKind": "named",
            "rule": null,
            "line": null,
            "note": null
          },
          "finalUrl": null,
          "crawlDelay": null,
          "directives": [],
          "docs": "https://developers.openai.com/api/docs/bots",
          "note": null
        }
      ]
    }
  ],
  "robotsTxt": {
    "url": "https://www.airbnb.com/robots.txt",
    "status": 200,
    "outcome": "found",
    "reason": null,
    "fetchedAt": "2026-10-24T17:15:30Z",
    "bytes": 20930,
    "truncated": false,
    "groups": 18,
    "rules": 711,
    "sitemaps": [
      "https://www.airbnb.com/sitemap-master-index.xml.gz"
    ],
    "contentSignals": [],
    "problems": [],
    "final": null
  },
  "llmsTxt": {
    "url": "https://www.airbnb.com/llms.txt",
    "finalUrl": "https://www.airbnb.com/404",
    "status": 404,
    "present": false,
    "valid": null,
    "servedHtml": true,
    "contentType": "text/html;charset=utf-8",
    "bytes": 2947,
    "truncated": false,
    "title": null,
    "summary": null,
    "sections": [],
    "links": 0,
    "problems": [],
    "note": null
  },
  "llmsFullTxt": {
    "url": "https://www.airbnb.com/llms-full.txt",
    "finalUrl": "https://www.airbnb.com/404",
    "status": 404,
    "present": false,
    "valid": null,
    "servedHtml": true,
    "contentType": "text/html;charset=utf-8",
    "bytes": 2947,
    "truncated": false,
    "title": null,
    "words": null,
    "problems": [],
    "note": null
  },
  "pageDirectives": {
    "checked": true,
    "note": null,
    "metaRobots": [],
    "botMetas": [
      {
        "name": "google",
        "content": "notranslate",
        "directives": [
          "notranslate"
        ],
        "agents": []
      }
    ],
    "xRobotsTag": [],
    "all": {
      "noindex": false,
      "nofollow": false,
      "noarchive": false,
      "nosnippet": false,
      "noimageindex": false,
      "notranslate": false,
      "noai": false,
      "noimageai": false,
      "maxSnippet": null,
      "maxImagePreview": null,
      "maxVideoPreview": null,
      "unavailableAfter": null
    }
  },
  "tdm": {
    "reserved": null,
    "source": null,
    "policy": null,
    "policySource": null,
    "problems": [],
    "headers": {
      "checked": true,
      "reservation": null,
      "policy": null
    },
    "meta": {
      "checked": true,
      "reservation": null,
      "policy": null
    },
    "tdmrepJson": {
      "url": "https://www.airbnb.com/.well-known/tdmrep.json",
      "status": 404,
      "present": false,
      "valid": null,
      "rules": null,
      "matchedRule": null,
      "problems": [],
      "note": null
    },
    "note": null
  },
  "firewall": {
    "vendor": null,
    "challenged": false,
    "kind": null,
    "signals": []
  },
  "rawHtml": {
    "checked": true,
    "note": null,
    "bytes": 664934,
    "truncated": false,
    "visibleWords": 511,
    "mainTextWords": 426,
    "mainTextMode": "article",
    "noscriptWords": 14,
    "scripts": {
      "inline": 13,
      "external": 40,
      "inlineBytes": 321685
    },
    "jsShell": false,
    "jsShellSignals": [
      "a <noscript> message asks for JavaScript",
      "321 KB of inline script against 3583 bytes of text"
    ],
    "frameworks": [],
    "generator": null
  },
  "registry": {
    "version": "2026-10-24",
    "agents": 274
  },
  "seenAs": {
    "agent": "Rankfield-User",
    "userAgent": "Mozilla/5.0 (compatible; Rankfield-User/1.0; +https://rankfield.dev/bot)",
    "page": {
      "allowed": true,
      "group": "*",
      "groupKind": "wildcard",
      "rule": null,
      "line": null,
      "note": null
    },
    "pageFetched": true
  },
  "cached": false,
  "ageSeconds": 0
}
```

```json 401
{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required"
  }
}
```

For one URL, the robots.txt verdict for every known crawler (search engines, AI training and AI search crawlers, assistants that fetch for a user, AI agents, SEO tools, link previews, archives and ad checkers), with the rule and line that decided it, grouped by company and summed up per purpose. Around it: robots.txt itself, llms.txt and llms-full.txt, the page's robots meta tags and X-Robots-Tag headers, TDMRep reservations, whether a firewall answered, and what the raw HTML gives a crawler that runs no JavaScript.

Send the parameters as a query string with `GET`, or as a JSON object (up to 1 MB) with `POST` to the same path. For many URLs, [start a job](/docs/bot-view/start-a-job).

## Parameters

### Headers

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

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `url` | string | Yes | – | The page, a full `http(s)` URL. |
| `agents` | string | No | `all` | Which crawlers to report, comma-separated: `all`; `ai` (every agent on the ai.robots.txt list); a purpose (`aiTraining`, `aiSearch`, `userFetch`, `aiAgent`, `dataProvider`, `search`, `ads`, `seo`, `linkPreview`, `archive`, `undocumented`); a company (`google`, `openai`…); or crawler names (`GPTBot`, `bingbot`…). Other robots.txt names are checked as given with `known: false`, up to 50. Case is ignored. |
| `rendered` | boolean | No | `false` | `true` also renders the page and compares it with the raw HTML. It's slower. See [Before and after JavaScript](#before-and-after-javascript). |
| `maxAge` | integer | No | `600` | How old a stored answer may be, in seconds, up to 2,592,000 (30 days). `0` fetches fresh. |
| `timeout` | integer | No | `20` | How long the call may take, in seconds, 1–60. |

## Response

| Field | Type | Description |
|---|---|---|
| `url`, `agents` | string, string[] | What you asked (`url` without its `#fragment`). |
| `finalUrl`, `status`, `redirects` |  | The page that answered. `null` and `[]` when the page was not fetched. |
| `summary` | object | `agents`, `allowed`, `blocked` (this page), `blockedSite` (on `/`), the same per purpose in `purposes`, and `robotsTxt`: `found`, `missing` or `unreachable`. |
| `companies` | array | `{company, agents}`. Each agent: `token`, `matchedAs`, `purpose`, `respectsRobots` (what the vendor says), `known`, `allowed`, the `page` and `site` verdicts, `crawlDelay`, `directives`, `docs` and `note`. |
| `page`, `site`, `finalUrl (verdicts)` | object | `{allowed, group, groupKind, rule, line, note}`. `groupKind`: `named`, `fallback` (such as Googlebot for Googlebot-Image), `wildcard` or `none`. |
| `robotsTxt` | object | `url`, `status`, `outcome`, `bytes`, how many `groups` and `rules`, `sitemaps`, `contentSignals` (such as `ai-train: no`) and `problems` by line. |
| `llmsTxt`, `llmsFullTxt` | object | Whether each file is there and valid by llmstxt.org: `present`, `valid`, `servedHtml` (the path answers a web page), `title`, `sections`, `links` or `words`, `problems`. |
| `pageDirectives` | object | `metaRobots`, `botMetas` (metas named after a crawler), `xRobotsTag`, and `all`: what applies to every crawler (`noindex`, `nofollow`, `noai`, `maxSnippet`…). |
| `tdm` | object | TDMRep: `reserved` (true, false or `null`), `source`, `policy`, and what each place said. |
| `firewall` | object \| null | `{vendor, challenged, kind, signals}` for the page we fetched. |
| `rawHtml` | object | `visibleWords` and `mainTextWords` without JavaScript, `jsShell` (an empty app shell) with `jsShellSignals`, `frameworks` and `generator`. |
| `registry` | object | `version` (date) and `agents`: the crawler list in use. |
| `seenAs` | object | Our own user agent and verdict, and whether we fetched the page. |
| `rendered` | object | With `rendered=true`: `headline`, `diff` and `robotsBlockedResources`, as in [Before and after JavaScript](#before-and-after-javascript). |
| `cached`, `ageSeconds` | boolean, integer | Whether this answer came from our store, and how old it is. |

## What the verdicts can and cannot tell you

The verdicts are what the site's robots.txt tells each crawler. We fetch only as ourselves, so we cannot see how a firewall or CDN treats each crawler: a site can block GPTBot at its firewall while its robots.txt allows it. `firewall` shows only how the site answered us.

robots.txt names may only hold letters, `-` and `_`, and parsers (Google's too) read `User-agent: MJ12bot` as `MJ`. Crawlers with digits, dots or spaces in their names are matched by that prefix; `matchedAs` shows it.

The crawler list is built from ai.robots.txt (MIT) and the vendors' own crawler pages; each agent links its vendor's docs.

## Before and after JavaScript

Googlebot runs a page's JavaScript; most AI crawlers don't. With `rendered=true`:

- `rendered.headline` says in one sentence what changes. For example: "Before rendering a crawler sees 0 words and 0 links; after rendering, 1,240 words and 38 links."
- `rendered.diff` has the details: words, links, title, canonical, description, meta robots, hreflang, structured data and H1.
- `rendered.robotsBlockedResources` lists the scripts and files robots.txt keeps from crawlers.

## How we fetch

We fetch as `Rankfield-User` (`Mozilla/5.0 (compatible; Rankfield-User/1.0; +https://rankfield.dev/bot)`), as plain HTML without running JavaScript, unless you ask for a rendered page or a screenshot.

- **robots.txt:** obeyed on every request and redirect, following the rules for `Rankfield-User`, or for `RankfieldBot` when the file has none for it, or `*` when it has neither. Requests: robots.txt, the page, then `/llms.txt`, `/llms-full.txt` and `/.well-known/tdmrep.json`: 5, or 6 with a redirect's new robots.txt; redirects add their hops. A robots.txt that answers with a server error counts as closed to us, as the standard says.
- **Firewalls:** a challenge, CAPTCHA or block page is reported in the answer, never worked around and never retried.
- **Never:** cookies, logins, proxies or other bots' names. JavaScript runs only when you ask for it.
- **Excluded sites:** Reddit, LinkedIn, Facebook, Instagram, X/Twitter and TikTok (subdomains included), Google search result pages, and sites whose owners asked us are never fetched.
- **Pace:** each website is fetched gently, shared by all customers, slower when its robots.txt sets a `Crawl-delay` or after a slow answer. Many URLs on one site go at that site's pace.

Repeat calls to the same website within about a minute can wait their turn for that site's slot. If the wait runs past the call's time limit (20 seconds by default), the call ends with `504` `timeout` and `details.reason` `sitePace`. It doesn't count as usage: retry after `Retry-After`, or allow a longer `timeout`.

More: [Rankfield crawlers](/bot).

## Errors

Errors are `{"error": {"code", "message", "details"}}`. Branch on `code`; `message` is for people.

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | A parameter is missing, unknown or malformed. |
| 401 | `unauthorized` | No valid API key. |
| 403 | `site_excluded` | The site is on the exclusion list. |
| 403 | `blocked` | The website's bot protection refused us. Reported at once and never worked around; `details` says which protection. Not counted as usage. |
| 422 | `address_not_public` | The host resolves to a private or internal address. |
| 429 | `busy` | Our fetch capacity is busy: the call was refused at once, waited 4 seconds without a turn, or its time limit ran out while it waited (then `details.reason` is `capacity`). Not counted as usage. Retry after `Retry-After` seconds. |
| 500 | `internal` | Our bug. Retry. |
| 502 | `fetch_failed` | The site could not be reached at all (its robots.txt did not answer). A page that fails after robots.txt answered still gives the verdicts. |
| 503 | `unavailable` | The service is restarting or briefly unavailable. Retry after `Retry-After`. (A full fetch capacity answers `429` `busy`.) |
| 504 | `timeout` | The website didn't answer within the call's time limit. When `details.reason` is `sitePace`, the call waited its turn for this website instead, which we fetch gently, shared by all customers: retry after `Retry-After`, or allow a longer `timeout`. |

A robots.txt that disallows us is not an error here: the verdicts still come back, and the page checks say they were not checked. Only answered calls and the `502` and website-side `504` errors count as usage; refusals, our own errors (`500`, `503`), `429` `busy` and a `504` with `details.reason` `sitePace` don't.

## Limits

No per-key limits. When the server is busy you get `429` `busy` with `Retry-After`. Waiting calls are served in turn across keys, so a key with a few calls is never stuck behind one with thousands.

## MCP

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


---

# Start a Bot View job
Source: https://rankfield.dev/docs/bot-view/start-a-job

Check up to 10,000 URLs with Bot View in one background job; each item takes the same parameters as a single call.

`POST https://rankfield.dev/v1/bot-view/jobs`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/bot-view/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: bot-view-2026-10-26' \
  -d '{"items":[{"url":"https://www.airbnb.com/"},{"url":"https://example.com/"}]}'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/bot-view/jobs",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": "bot-view-2026-10-26"},
    json={"items": [{"url": "https://www.airbnb.com/"}, {"url": "https://example.com/"}]},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bot-view/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "bot-view-2026-10-26",
  },
  body: JSON.stringify({"items":[{"url":"https://www.airbnb.com/"},{"url":"https://example.com/"}]}),
});
console.log(await response.json());
```

```json 202
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "queued",
    "total": 2,
    "done": 0,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": null,
    "expiresAt": null
  }
}
```

```json 409
{
  "error": {
    "code": "invalid_input",
    "message": "This Idempotency-Key was used for different items"
  }
}
```

## 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 | Yes | – | 1–200 characters you choose for this job. Sending the same key with the same body again returns the same job instead of a new one. |

### Body

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `items` | object[] | Yes | – | 1–10,000 items. Each takes the same parameters as [Check how crawlers see a page](/docs/bot-view/check-a-page), as a JSON object. |

Every item is checked before the job starts. If any is invalid, the whole request is a `400` listing the first 20 (`index` and `message`).

## Response

`202` with `job`. A byte-identical body with the same `Idempotency-Key` replays the job (`200`, `Idempotency-Replayed: true`); any other body with that key is `409`.

| Field | Type | Description |
|---|---|---|
| `job.id` | string | The job id. |
| `job.status` | string | `queued`, `running`, `done` or `canceled`. |
| `job.total` | integer | URLs in the job. |
| `job.done` | integer | Items that succeeded. |
| `job.failed` | integer | Items that failed. |
| `job.createdAt`, `job.finishedAt` | string \| null | When it was created and when it finished (UTC). |
| `job.expiresAt` | string \| null | When its results are deleted: 24 hours after it finishes. |

A job runs 16 items at a time. An item counts as usage once the job accepts it, whatever its outcome. Items use the endpoint's default `timeout` rather than their own, and retry `busy` by themselves (up to 10 times). Follow it with [Get a Bot View job](/docs/bot-view/get-a-job) and read items with [Get Bot View job results](/docs/bot-view/get-results).

## Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | No `Idempotency-Key`, no items, too many items, or an invalid item. |
| 401 | `unauthorized` | No valid API key. |
| 409 | `invalid_input` | The `Idempotency-Key` was used before with a different body. |
| 429 | `busy` | The batch queue is full: 200,000 items from all keys are already waiting. Retry after `Retry-After` (60 seconds). |
| 503 | `unavailable` | Batch jobs are paused (storage). Retry after `Retry-After` (300 seconds). |

## Limits

Send up to 10,000 URLs in one job, and as many jobs as you like. No per-key limits. Jobs from all keys share one queue: when 200,000 items are already waiting, a new job answers `429` `busy` with `Retry-After` (60 seconds).

## MCP

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


---

# Get a Bot View job
Source: https://rankfield.dev/docs/bot-view/get-a-job

Check a Bot View job: its status, how many items are done and failed, and when its results expire.

`GET https://rankfield.dev/v1/bot-view/jobs/{id}`

```bash cURL
curl 'https://rankfield.dev/v1/bot-view/jobs/8f14e45fceea167a5a36dedd4bea2543' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/bot-view/jobs/8f14e45fceea167a5a36dedd4bea2543",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bot-view/jobs/8f14e45fceea167a5a36dedd4bea2543", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "running",
    "total": 2,
    "done": 1,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": null,
    "expiresAt": null
  }
}
```

## 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 from [Start a Bot View job](/docs/bot-view/start-a-job). |

## Response

| Field | Type | Description |
|---|---|---|
| `job.id` | string | The job id. |
| `job.status` | string | `queued`, `running`, `done` or `canceled`. |
| `job.total` | integer | URLs in the job. |
| `job.done` | integer | Items that succeeded. |
| `job.failed` | integer | Items that failed. |
| `job.createdAt`, `job.finishedAt` | string \| null | When it was created and when it finished (UTC). |
| `job.expiresAt` | string \| null | When its results are deleted: 24 hours after it finishes. |

Only the key that started a job can read it; any other key gets `404`.

## Errors

| Status | Code | When |
|---|---|---|
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |


---

# Get Bot View job results
Source: https://rankfield.dev/docs/bot-view/get-results

Read a Bot View job's items as each one finishes, with its full answer or error, and page through them with a cursor.

`GET https://rankfield.dev/v1/bot-view/jobs/{id}/results`

```bash cURL
curl 'https://rankfield.dev/v1/bot-view/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/bot-view/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bot-view/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "done",
    "total": 2,
    "done": 1,
    "failed": 1,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": "2026-10-26T18:00:04Z",
    "expiresAt": "2026-10-27T18:00:04Z"
  },
  "cursor": "2",
  "hasMore": false,
  "items": [
    { "index": 0, "ok": true, "result": { "…": "the same answer as a single call" } },
    { "index": 1, "ok": false, "error": { "code": "fetch_failed", "message": "…", "details": { "reason": "dns" } } }
  ]
}
```

## 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 from [Start a Bot View job](/docs/bot-view/start-a-job). |

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `cursor` | integer | No | `0` | Where to continue: the `cursor` of the previous answer (returned as a string; send it back as it is). |
| `limit` | integer | No | `100` | Items per answer, 1–500. |

## Read results

Start with `cursor=0`. Read `items`, then ask again with the returned `cursor` while `hasMore` is `true`. Items arrive in the order they finish; `index` is the item's position in your `items`, from 0.

| Field | Type | Description |
|---|---|---|
| `job` | object | The job, as in [Get a Bot View job](/docs/bot-view/get-a-job). |
| `items[].index` | integer | Position in your `items`. |
| `items[].ok` | boolean | Whether the item succeeded. |
| `items[].result` | object | The same answer as [Check how crawlers see a page](/docs/bot-view/check-a-page). |
| `items[].error` | object | `{code, message, details}`, as a single call's error. |
| `cursor` | string | Pass it back to continue. |
| `hasMore` | boolean | Whether more items exist now or will. |

## Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | `cursor` or `limit` is invalid. |
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |

## MCP

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


---

# Cancel a Bot View job
Source: https://rankfield.dev/docs/bot-view/cancel-a-job

Stop a Bot View job. Items already finished stay readable for 24 hours; items not started are dropped.

`POST https://rankfield.dev/v1/bot-view/jobs/{id}/cancel`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/bot-view/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/bot-view/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bot-view/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "canceled",
    "total": 2,
    "done": 1,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": "2026-10-26T18:00:04Z",
    "expiresAt": "2026-10-27T18:00:04Z"
  }
}
```

## 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 from [Start a Bot View job](/docs/bot-view/start-a-job). |

## Response

The job, now `canceled`, as in [Get a Bot View job](/docs/bot-view/get-a-job). Items already running finish; nothing new starts. A job that has already finished is returned unchanged (its status stays `done`).

## Errors

| Status | Code | When |
|---|---|---|
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |


---

# Brand
Source: https://rankfield.dev/docs/brand

Get a company's brand from its domain: name, description, logos, icons, colours, fonts, social profiles and contact details.

Brand reads a company's own homepage, manifest and stylesheets and returns its identity, each value with the place it came from. One call per domain, or a job for up to 10,000 domains.

## Pages

- [Get a company's brand](/docs/brand/get-a-brand): Get a company's name, description, logos, icons, colours, fonts, social profiles and published contact details from its domain.
- [Start a Brand job](/docs/brand/start-a-job): Get the brands of up to 10,000 domains in one background job; each item takes the same parameters as a single call.
- [Get a Brand job](/docs/brand/get-a-job): Check a Brand job: its status, how many items are done and failed, and when its results expire.
- [Get Brand job results](/docs/brand/get-results): Read a Brand job's items as each one finishes, with its full answer or error, and page through them with a cursor.
- [Cancel a Brand job](/docs/brand/cancel-a-job): Stop a Brand job. Items already finished stay readable for 24 hours; items not started are dropped.
:::


---

# Get a company's brand
Source: https://rankfield.dev/docs/brand/get-a-brand

Get a company's name, description, logos, icons, colours, fonts, social profiles and published contact details from its domain.

`GET https://rankfield.dev/v1/brand?domain={domain}`

```bash cURL
curl 'https://rankfield.dev/v1/brand?domain=rankfield.dev' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/brand?domain=rankfield.dev",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/brand?domain=rankfield.dev", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "domain": "rankfield.dev",
  "finalUrl": "https://rankfield.dev/",
  "status": 200,
  "blocked": null,
  "name": {
    "value": "Rankfield",
    "source": "title"
  },
  "description": {
    "value": "Get a key without signing up and query Site Strength and referring domain metrics.",
    "source": "meta description"
  },
  "logos": [
    {
      "url": "data:image/svg+xml,%3Csvg%20class=%22brand-mark%22%20aria-hidden=%22true%22%20xmlns=%22http://www.w3.org/2000/svg%22%20viewBox=%220%200%2064%2064%22%3E%3Crect%20x=%228%22%20y=%2231%22%20width=%2212%22%20height=%2226%22%20rx=%224%22%20fill=%22%23ff766a%22%20stroke=%22%23252238%22%20stroke-width=%222.5%22%3E%3C/rect%3E%3Crect%20x=%2226%22%20y=%229%22%20width=%2212%22%20height=%2248%22%20rx=%224%22%20fill=%22%238067ed%22%20stroke=%22%23252238%22%20stroke-width=%222.5%22%3E%3C/rect%3E%3Crect%20x=%2244%22%20y=%2221%22%20width=%2212%22%20height=%2236%22%20rx=%224%22%20fill=%22%236edfc5%22%20stroke=%22%23252238%22%20stroke-width=%222.5%22%3E%3C/rect%3E%3C/svg%3E",
      "source": "header inline <svg>",
      "confidence": 0.88,
      "type": "image/svg+xml",
      "width": null,
      "height": null,
      "variant": null,
      "colors": [
        "#ff766a",
        "#8067ed",
        "#6edfc5",
        "…"
      ],
      "fallback": false
    }
  ],
  "logosReason": null,
  "wordmark": null,
  "icons": {
    "best": {
      "url": "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2064%2064%22%3E%3Crect%20x%3D%228%22%20y%3D%2231%22%20width%3D%2212%22%20height%3D%2226%22%20rx%3D%224%22%20fill%3D%22%23ff766a%22%20stroke%3D%22%23252238%22%20stroke-width%3D%222.5%22%2F%3E%3Crect%20x%3D%2226%22%20y%3D%229%22%20width%3D%2212%22%20height%3D%2248%22%20rx%3D%224%22%20fill%3D%22%238067ed%22%20stroke%3D%22%23252238%22%20stroke-width%3D%222.5%22%2F%3E%3Crect%20x%3D%2244%22%20y%3D%2221%22%20width%3D%2212%22%20height%3D%2236%22%20rx%3D%224%22%20fill%3D%22%236edfc5%22%20stroke%3D%22%23252238%22%20stroke-width%3D%222.5%22%2F%3E%3C%2Fsvg%3E",
      "sizes": null,
      "type": "image/svg+xml",
      "source": "link rel=icon"
    },
    "favicon": [
      {
        "url": "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2064%2064%22%3E%3Crect%20x%3D%228%22%20y%3D%2231%22%20width%3D%2212%22%20height%3D%2226%22%20rx%3D%224%22%20fill%3D%22%23ff766a%22%20stroke%3D%22%23252238%22%20stroke-width%3D%222.5%22%2F%3E%3Crect%20x%3D%2226%22%20y%3D%229%22%20width%3D%2212%22%20height%3D%2248%22%20rx%3D%224%22%20fill%3D%22%238067ed%22%20stroke%3D%22%23252238%22%20stroke-width%3D%222.5%22%2F%3E%3Crect%20x%3D%2244%22%20y%3D%2221%22%20width%3D%2212%22%20height%3D%2236%22%20rx%3D%224%22%20fill%3D%22%236edfc5%22%20stroke%3D%22%23252238%22%20stroke-width%3D%222.5%22%2F%3E%3C%2Fsvg%3E",
        "sizes": null,
        "type": "image/svg+xml",
        "source": "link rel=icon"
      }
    ],
    "appleTouch": [],
    "manifest": [],
    "maskIcon": null
  },
  "images": {
    "ogImage": null,
    "twitterImage": null
  },
  "colors": {
    "themeColor": [],
    "manifest": {
      "theme": null,
      "background": null
    },
    "cssVariables": [
      {
        "name": "--ink",
        "value": "#252238",
        "hex": "#252238",
        "uses": 106,
        "stock": false
      },
      {
        "name": "--lime",
        "value": "#dff582",
        "hex": "#dff582",
        "uses": 11,
        "stock": false
      },
      {
        "name": "--line",
        "value": "#252238",
        "hex": "#252238",
        "uses": 10,
        "stock": false
      },
      "…"
    ],
    "mostUsed": [
      {
        "hex": "#252238",
        "count": 131,
        "neutral": false,
        "score": 450,
        "stock": false,
        "seen": [
          "button",
          "header",
          "nav",
          "…"
        ]
      },
      {
        "hex": "#ffffff",
        "count": 35,
        "neutral": true,
        "score": 164,
        "stock": false,
        "seen": [
          "button",
          "header",
          "body"
        ]
      },
      {
        "hex": "#35304f",
        "count": 10,
        "neutral": false,
        "score": 61,
        "stock": false,
        "seen": [
          "button"
        ]
      },
      "…"
    ],
    "roles": {
      "primary": {
        "hex": "#ffb9ce",
        "from": "button background",
        "element": "body>header.site-header>nav.top-nav>a.nav-key",
        "method": "computed"
      },
      "accent": null,
      "background": {
        "hex": "#f5f1e9",
        "from": "body background",
        "element": "body",
        "method": "computed"
      },
      "text": {
        "hex": "#252238",
        "from": "body colour",
        "element": "body",
        "method": "computed"
      },
      "headerBackground": {
        "hex": "#fffaf3f5",
        "from": "header background",
        "element": "body>header.site-header",
        "method": "computed"
      }
    },
    "rolesDark": null,
    "rolesReason": null
  },
  "fonts": [
    {
      "family": "Inter",
      "source": "css font-family",
      "uses": 5
    },
    {
      "family": "Trebuchet MS",
      "source": "css font-family",
      "uses": 3
    },
    {
      "family": "Avenir Next",
      "source": "css font-family",
      "uses": 1
    }
  ],
  "typography": {
    "method": "stylesheet",
    "viewport": {
      "width": 1280.0,
      "height": 800.0
    },
    "rootFontSize": {
      "px": 16.0,
      "basis": "16px: the CSS default (html declares no font-size)"
    },
    "body": {
      "family": {
        "value": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "declared": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "primary": "Trebuchet MS",
        "generic": false,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": null
      },
      "size": {
        "value": "15px",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "px": 15.0,
        "basis": "px",
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": null
      },
      "weight": {
        "value": "normal",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "number": 400.0,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": null
      },
      "lineHeight": {
        "value": "1.5",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "px": 22.5,
        "basis": "1.5 × font size 15px",
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": null
      },
      "letterSpacing": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared for body nor on html"
      }
    },
    "h1": {
      "family": {
        "value": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "declared": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "primary": "Trebuchet MS",
        "generic": false,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "size": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: the browser default for h1 is 2em"
      },
      "weight": {
        "value": null,
        "declared": null,
        "number": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: browsers make headings bold"
      },
      "lineHeight": {
        "value": "1.5",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "px": null,
        "basis": null,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": "1.5 × the font size, which isn't declared"
      },
      "letterSpacing": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared for h1 nor on body"
      }
    },
    "h2": {
      "family": {
        "value": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "declared": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "primary": "Trebuchet MS",
        "generic": false,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "size": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: the browser default for h2 is 1.5em"
      },
      "weight": {
        "value": null,
        "declared": null,
        "number": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: browsers make headings bold"
      },
      "lineHeight": {
        "value": "1.5",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "px": null,
        "basis": null,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": "1.5 × the font size, which isn't declared"
      },
      "letterSpacing": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared for h2 nor on body"
      }
    },
    "h3": {
      "family": {
        "value": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "declared": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "primary": "Trebuchet MS",
        "generic": false,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "size": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: the browser default for h3 is 1.17em"
      },
      "weight": {
        "value": null,
        "declared": null,
        "number": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: browsers make headings bold"
      },
      "lineHeight": {
        "value": "1.5",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "px": null,
        "basis": null,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": "1.5 × the font size, which isn't declared"
      },
      "letterSpacing": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared for h3 nor on body"
      }
    },
    "h4": {
      "family": {
        "value": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "declared": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "primary": "Trebuchet MS",
        "generic": false,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "size": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: the browser default for h4 is 1em"
      },
      "weight": {
        "value": null,
        "declared": null,
        "number": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: browsers make headings bold"
      },
      "lineHeight": {
        "value": "1.5",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "px": null,
        "basis": null,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": "1.5 × the font size, which isn't declared"
      },
      "letterSpacing": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared for h4 nor on body"
      }
    },
    "h5": {
      "family": {
        "value": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "declared": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "primary": "Trebuchet MS",
        "generic": false,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "size": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: the browser default for h5 is 0.83em"
      },
      "weight": {
        "value": null,
        "declared": null,
        "number": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: browsers make headings bold"
      },
      "lineHeight": {
        "value": "1.5",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "px": null,
        "basis": null,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": "1.5 × the font size, which isn't declared"
      },
      "letterSpacing": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared for h5 nor on body"
      }
    },
    "h6": {
      "family": {
        "value": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "declared": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "primary": "Trebuchet MS",
        "generic": false,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "size": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: the browser default for h6 is 0.67em"
      },
      "weight": {
        "value": null,
        "declared": null,
        "number": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: browsers make headings bold"
      },
      "lineHeight": {
        "value": "1.5",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "px": null,
        "basis": null,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": "1.5 × the font size, which isn't declared"
      },
      "letterSpacing": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared for h6 nor on body"
      }
    },
    "button": {
      "family": {
        "value": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "declared": "inherit",
        "primary": "Trebuchet MS",
        "generic": false,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "size": {
        "value": "15px",
        "declared": "font: inherit",
        "px": 15.0,
        "basis": "px",
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "weight": {
        "value": "normal",
        "declared": "font: inherit",
        "number": 400.0,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "lineHeight": {
        "value": "1.5",
        "declared": "font: inherit",
        "px": 22.5,
        "basis": "1.5 × font size 15px",
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "letterSpacing": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared: buttons use the browser's own control font"
      }
    },
    "link": {
      "family": {
        "value": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "declared": "\"Trebuchet MS\",\"Avenir Next\",Arial,sans-serif",
        "primary": "Trebuchet MS",
        "generic": false,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "size": {
        "value": "15px",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "px": 15.0,
        "basis": "px",
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "weight": {
        "value": "normal",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "number": 400.0,
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "lineHeight": {
        "value": "1.5",
        "declared": "font: 15px/1.5 \"Avenir Next\",Arial,Helvetica,sans-serif",
        "px": 22.5,
        "basis": "1.5 × font size 15px",
        "source": "style element",
        "selector": "body",
        "media": null,
        "inherited": "body",
        "method": "stylesheet",
        "reason": null
      },
      "letterSpacing": {
        "value": null,
        "declared": null,
        "px": null,
        "basis": null,
        "source": null,
        "selector": null,
        "media": null,
        "inherited": null,
        "method": "stylesheet",
        "reason": "not declared for link nor on body"
      }
    }
  },
  "social": [],
  "contact": {
    "source": null,
    "email": null,
    "telephone": null,
    "address": null,
    "contactPoints": []
  },
  "language": {
    "code": "en",
    "script": "Latn",
    "confidence": 1.0,
    "source": "content",
    "declared": "en"
  },
  "fetches": [
    {
      "url": "https://rankfield.dev/robots.txt",
      "purpose": "robots.txt",
      "status": 404,
      "bytes": null,
      "error": null
    },
    {
      "url": "https://rankfield.dev/",
      "purpose": "page",
      "status": 200,
      "bytes": 133865,
      "error": null
    }
  ],
  "cached": false,
  "ageSeconds": 0
}
```

```json 401
{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required"
  }
}
```

We read the homepage, its web app manifest, up to 4 of its own stylesheets (on its own host or its CDN), and `/favicon.ico` when the page names no icon: 8 requests at most, robots.txt included. Every value says where on the site it came from, so you can judge how far to trust it.

Send the parameters as a query string with `GET`, or as a JSON object (up to 1 MB) with `POST` to the same path. For many domains, [start a job](/docs/brand/start-a-job).

## Parameters

### Headers

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

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `domain` | string | Yes, or `url` | – | The company's domain, such as `acme.com`. `www.acme.com` is read as given; a URL here means its domain. Send `domain` or `url`, not both. |
| `url` | string | Instead of `domain` | – | A full `http(s)` URL on the site. The site's homepage is read, not this page. |
| `roles` | boolean | No | `false` | `true` computes the colour roles on a large page too. By default they are computed on pages up to about 6,000 tags and 1.6 MB of CSS, four times the earlier limit: almost every small-business site and most large brand homepages. On a larger page `colors.roles` is `null` with a reason unless you ask. On a very large page even `roles=true` can come back `null` with `over the CPU budget`. A call with `roles=true` is stored apart from one without. |
| `screenshot` | string | No | – | `viewport` or `fullPage`: also return a WebP image of the homepage as a browser shows it, the first screen or the whole page up to 12,000 px tall. |
| `viewport` | string | No | `desktop` | `desktop` (1366×768) or `mobile` (412×915): the screen for the screenshot. |
| `maxAge` | integer | No | `86400` | How old a stored answer may be, in seconds, up to 2,592,000 (30 days). `0` fetches fresh. |
| `timeout` | integer | No | `20` | How long the call may take, in seconds, 1–60. |

## Response

| Field | Type | Description |
|---|---|---|
| `url` | string | The URL you sent, when you sent one. |
| `domain` | string | The site read (lowercase; international names in `xn--` form). |
| `finalUrl`, `status` | string, integer | The homepage that answered, and its HTTP status. On a 404 or 500 every brand field is empty. |
| `blocked` | object \| null | The firewall that answered instead of the homepage. Then every brand field is empty: we never guess. |
| `name` | object | `{value, source}`. Sources, best first: schema.org Organization, schema.org WebSite, `og:site_name`, `application-name`, `apple-mobile-web-app-title`, the manifest, the title. |
| `description` | object | `{value, source}`. Sources, best first: schema.org Organization, the meta description, `og:description`, `twitter:description`, schema.org WebSite, the manifest. |
| `logos` | array | The site's own logos, best first, each `{url, source, confidence, type, width, height, variant, fallback}`: the logo the page shows in its header or link home (an image, or an inline SVG as a `data:` URL with its `colors`), then the schema.org logo (marked when it differs from the one the page shows) and `og:logo`. Never a favicon or share image: those are in `icons` and `images`, with one exception. When the page has no logo image, the site's best icon (`icons.best`) stands in as the only entry, with `fallback: true`, a `source` of `icon fallback (…)` naming where the icon came from, and `confidence` 0.3. Every real logo has `fallback: false`. `variant` is `light` for a logo drawn for dark backgrounds, `dark` for the opposite, or `null`. Image-proxy URLs (`/_next/image?url=…`) are given as the original file. |
| `logosReason` | string \| null | Why `logos` is empty, or holds only the fallback icon, when it does. |
| `wordmark` | object \| null | `{text, source: "home link text"}`: the site's name as the page sets it in type, from its first link home when that link holds no image and its text names the site (the domain's name or the brand name, such as `KYLIAN` on kylian.ai). Menu items, skip links and written-out addresses are left out. `null` otherwise. |
| `icons` | object | `best`, the one icon to show the site by: an SVG icon (it scales), else the largest declared size; `null` when the site declares none. Then the `favicon`, `appleTouch` and `manifest` lists, and `maskIcon`. Each icon is `{url, sizes, type, source}`, manifest icons with `purpose`. |
| `images` | object | `ogImage` and `twitterImage`. |
| `colors` | object | `themeColor` (with light and dark variants), the manifest's `theme` and `background`, `cssVariables` (custom properties holding colours, with how often they are used) and `mostUsed` (colours across the CSS read, weighted by where they paint: `score`, and `seen`, the roles they paint). `neutral` marks greys, black and white; `stock` marks a shared framework's default colours (WordPress presets, Bootstrap, Tailwind's palette, shadcn/ui's greys), ranked after the site's own. Each has a `hex`. |
| `colors.roles` | object \| null | The colours the page's own elements get, computed by a style engine over the page and its stylesheets: `primary` (the main button's background, else the link colour, else a coloured header), `accent` (the link colour when it differs), `background` and `text` (body), and `headerBackground`. Each is `{hex, from, element, method: "computed"}`. `null` when not computed, with `rolesReason`. |
| `colors.rolesDark` | object \| null | The same roles in the visitor's dark mode, when the site has one. |
| `colors.rolesReason` | string \| null | Why `roles` is `null`: `a large page: colour roles are computed when asked (roles=true)`, `the page or its stylesheets are over the size cap`, `the page has too much markup for the pass`, `over the CPU budget`, `no <body>` or `the style engine failed on this page`. `null` when the roles are there. |
| `fonts` | array | `{family, source, uses}`: Google Fonts, `@font-face`, Adobe Fonts, then fonts the CSS asks for. |
| `typography` | object \| null | The site's base typography, read from its CSS as a 1280 × 800 desktop window applies it: `rootFontSize`, and for `body`, `h1`–`h6`, `button` and `link` the `family`, `size`, `weight`, `lineHeight` and `letterSpacing`. Each value has `value` (in force, `var()` resolved, or `null`), `declared` (as written), `px` with its `basis` for lengths, `number` for weight, `primary` and `generic` for families, its `source` stylesheet (or `style element`), `selector`, `media`, `inherited` (`body` or `html`) and, when `null`, a `reason` naming the browser default. `null` on a blocked or error page. |
| `social` | array | `{network, url, source}` from schema.org `sameAs`, then links to known social sites. Never visited. |
| `contact` | object | `{source, email, telephone, address, contactPoints}`, only from the site's own schema.org Organization or LocalBusiness data. |
| `language` | object | The homepage's language. |
| `fetches` | array | Each request made: `{url, purpose, status, bytes, error}`. |
| `screenshot` | object | With `screenshot`: `{format: "webp", kind, viewport, bytes, data}`, the image in base64. |
| `cached`, `ageSeconds` | boolean, integer | Whether this answer came from our store, and how old it is. |

Colour roles are computed on the page as fetched, without JavaScript: a page whose buttons get their colours from script gets the colours of its static HTML and CSS.

Names and descriptions never carry an email address or phone number: where the site's text has one, it shows as "…". Contact details only appear in `contact`.

`typography` reads the site's base rules (`body`, `h1`, `h1, .h1`, `button` and `.btn`, `a`), not each widget's styling. Nothing is guessed: a value the CSS does not declare is `null`, with a `reason`.

## How we fetch

We fetch as `Rankfield-User` (`Mozilla/5.0 (compatible; Rankfield-User/1.0; +https://rankfield.dev/bot)`), as plain HTML without running JavaScript, unless you ask for a rendered page or a screenshot.

- **robots.txt:** obeyed on every request and redirect, following the rules for `Rankfield-User`, or for `RankfieldBot` when the file has none for it, or `*` when it has neither. Social sites and font services are named from their links, never fetched.
- **Firewalls:** a challenge, CAPTCHA or block page is reported in the answer, never worked around and never retried.
- **Never:** cookies, logins, proxies or other bots' names. JavaScript runs only when you ask for it.
- **Excluded sites:** Reddit, LinkedIn, Facebook, Instagram, X/Twitter and TikTok (subdomains included), Google search result pages, and sites whose owners asked us are never fetched.
- **Pace:** each website is fetched gently, shared by all customers, slower when its robots.txt sets a `Crawl-delay` or after a slow answer. Many URLs on one site go at that site's pace.

Repeat calls to the same website within about a minute can wait their turn for that site's slot. If the wait runs past the call's time limit (20 seconds by default), the call ends with `504` `timeout` and `details.reason` `sitePace`. It doesn't count as usage: retry after `Retry-After`, or allow a longer `timeout`.

More: [Rankfield crawlers](/bot).

## Errors

Errors are `{"error": {"code", "message", "details"}}`. Branch on `code`; `message` is for people.

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | A parameter is missing, unknown or malformed. |
| 401 | `unauthorized` | No valid API key. |
| 403 | `robots_disallowed` | robots.txt disallows Rankfield-User for the homepage (a server error counts as no); `details` has the rule and line. |
| 403 | `site_excluded` | The site is on the exclusion list. |
| 403 | `blocked` | The website's bot protection refused us. Reported at once and never worked around; `details` says which protection. Not counted as usage. |
| 415 | `unsupported_content_type` | The homepage answered 2xx but isn't HTML. |
| 422 | `address_not_public` | The host resolves to a private or internal address. |
| 429 | `busy` | Our fetch capacity is busy: the call was refused at once, waited 4 seconds without a turn, or its time limit ran out while it waited (then `details.reason` is `capacity`). Not counted as usage. Retry after `Retry-After` seconds. |
| 500 | `internal` | Our bug. Retry. |
| 502 | `fetch_failed` | The site could not be reached: DNS failed, neither https nor http connected, or more than 5 redirects. |
| 503 | `unavailable` | The service is restarting or briefly unavailable. Retry after `Retry-After`. (A full fetch capacity answers `429` `busy`.) |
| 504 | `timeout` | The website didn't answer within the call's time limit. When `details.reason` is `sitePace`, the call waited its turn for this website instead, which we fetch gently, shared by all customers: retry after `Retry-After`, or allow a longer `timeout`. |

Only answered calls and the `502` and website-side `504` errors count as usage; refusals, our own errors (`500`, `503`), `429` `busy` and a `504` with `details.reason` `sitePace` don't.

## Limits

No per-key limits. When the server is busy you get `429` `busy` with `Retry-After`. Waiting calls are served in turn across keys, so a key with a few calls is never stuck behind one with thousands.

## MCP

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


---

# Start a Brand job
Source: https://rankfield.dev/docs/brand/start-a-job

Get the brands of up to 10,000 domains in one background job; each item takes the same parameters as a single call.

`POST https://rankfield.dev/v1/brand/jobs`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/brand/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: brand-2026-10-26' \
  -d '{"items":[{"domain":"rankfield.dev"},{"domain":"example.com"}]}'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/brand/jobs",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": "brand-2026-10-26"},
    json={"items": [{"domain": "rankfield.dev"}, {"domain": "example.com"}]},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/brand/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "brand-2026-10-26",
  },
  body: JSON.stringify({"items":[{"domain":"rankfield.dev"},{"domain":"example.com"}]}),
});
console.log(await response.json());
```

```json 202
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "queued",
    "total": 2,
    "done": 0,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": null,
    "expiresAt": null
  }
}
```

```json 409
{
  "error": {
    "code": "invalid_input",
    "message": "This Idempotency-Key was used for different items"
  }
}
```

## 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 | Yes | – | 1–200 characters you choose for this job. Sending the same key with the same body again returns the same job instead of a new one. |

### Body

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `items` | object[] | Yes | – | 1–10,000 items. Each takes the same parameters as [Get a company's brand](/docs/brand/get-a-brand), as a JSON object. |

Every item is checked before the job starts. If any is invalid, the whole request is a `400` listing the first 20 (`index` and `message`).

## Response

`202` with `job`. A byte-identical body with the same `Idempotency-Key` replays the job (`200`, `Idempotency-Replayed: true`); any other body with that key is `409`.

| Field | Type | Description |
|---|---|---|
| `job.id` | string | The job id. |
| `job.status` | string | `queued`, `running`, `done` or `canceled`. |
| `job.total` | integer | Domains in the job. |
| `job.done` | integer | Items that succeeded. |
| `job.failed` | integer | Items that failed. |
| `job.createdAt`, `job.finishedAt` | string \| null | When it was created and when it finished (UTC). |
| `job.expiresAt` | string \| null | When its results are deleted: 24 hours after it finishes. |

A job runs 16 items at a time. An item counts as usage once the job accepts it, whatever its outcome. Items use the endpoint's default `timeout` rather than their own, and retry `busy` by themselves (up to 10 times). Follow it with [Get a Brand job](/docs/brand/get-a-job) and read items with [Get Brand job results](/docs/brand/get-results).

## Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | No `Idempotency-Key`, no items, too many items, or an invalid item. |
| 401 | `unauthorized` | No valid API key. |
| 409 | `invalid_input` | The `Idempotency-Key` was used before with a different body. |
| 429 | `busy` | The batch queue is full: 200,000 items from all keys are already waiting. Retry after `Retry-After` (60 seconds). |
| 503 | `unavailable` | Batch jobs are paused (storage). Retry after `Retry-After` (300 seconds). |

## Limits

Send up to 10,000 domains in one job, and as many jobs as you like. No per-key limits. Jobs from all keys share one queue: when 200,000 items are already waiting, a new job answers `429` `busy` with `Retry-After` (60 seconds).

## MCP

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


---

# Get a Brand job
Source: https://rankfield.dev/docs/brand/get-a-job

Check a Brand job: its status, how many items are done and failed, and when its results expire.

`GET https://rankfield.dev/v1/brand/jobs/{id}`

```bash cURL
curl 'https://rankfield.dev/v1/brand/jobs/8f14e45fceea167a5a36dedd4bea2543' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/brand/jobs/8f14e45fceea167a5a36dedd4bea2543",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/brand/jobs/8f14e45fceea167a5a36dedd4bea2543", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "running",
    "total": 2,
    "done": 1,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": null,
    "expiresAt": null
  }
}
```

## 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 from [Start a Brand job](/docs/brand/start-a-job). |

## Response

| Field | Type | Description |
|---|---|---|
| `job.id` | string | The job id. |
| `job.status` | string | `queued`, `running`, `done` or `canceled`. |
| `job.total` | integer | Domains in the job. |
| `job.done` | integer | Items that succeeded. |
| `job.failed` | integer | Items that failed. |
| `job.createdAt`, `job.finishedAt` | string \| null | When it was created and when it finished (UTC). |
| `job.expiresAt` | string \| null | When its results are deleted: 24 hours after it finishes. |

Only the key that started a job can read it; any other key gets `404`.

## Errors

| Status | Code | When |
|---|---|---|
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |


---

# Get Brand job results
Source: https://rankfield.dev/docs/brand/get-results

Read a Brand job's items as each one finishes, with its full answer or error, and page through them with a cursor.

`GET https://rankfield.dev/v1/brand/jobs/{id}/results`

```bash cURL
curl 'https://rankfield.dev/v1/brand/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/brand/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/brand/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "done",
    "total": 2,
    "done": 1,
    "failed": 1,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": "2026-10-26T18:00:04Z",
    "expiresAt": "2026-10-27T18:00:04Z"
  },
  "cursor": "2",
  "hasMore": false,
  "items": [
    { "index": 0, "ok": true, "result": { "…": "the same answer as a single call" } },
    { "index": 1, "ok": false, "error": { "code": "fetch_failed", "message": "…", "details": { "reason": "dns" } } }
  ]
}
```

## 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 from [Start a Brand job](/docs/brand/start-a-job). |

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `cursor` | integer | No | `0` | Where to continue: the `cursor` of the previous answer (returned as a string; send it back as it is). |
| `limit` | integer | No | `100` | Items per answer, 1–500. |

## Read results

Start with `cursor=0`. Read `items`, then ask again with the returned `cursor` while `hasMore` is `true`. Items arrive in the order they finish; `index` is the item's position in your `items`, from 0.

| Field | Type | Description |
|---|---|---|
| `job` | object | The job, as in [Get a Brand job](/docs/brand/get-a-job). |
| `items[].index` | integer | Position in your `items`. |
| `items[].ok` | boolean | Whether the item succeeded. |
| `items[].result` | object | The same answer as [Get a company's brand](/docs/brand/get-a-brand). |
| `items[].error` | object | `{code, message, details}`, as a single call's error. |
| `cursor` | string | Pass it back to continue. |
| `hasMore` | boolean | Whether more items exist now or will. |

## Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | `cursor` or `limit` is invalid. |
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |

## MCP

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


---

# Cancel a Brand job
Source: https://rankfield.dev/docs/brand/cancel-a-job

Stop a Brand job. Items already finished stay readable for 24 hours; items not started are dropped.

`POST https://rankfield.dev/v1/brand/jobs/{id}/cancel`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/brand/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/brand/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/brand/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "canceled",
    "total": 2,
    "done": 1,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": "2026-10-26T18:00:04Z",
    "expiresAt": "2026-10-27T18:00:04Z"
  }
}
```

## 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 from [Start a Brand job](/docs/brand/start-a-job). |

## Response

The job, now `canceled`, as in [Get a Brand job](/docs/brand/get-a-job). Items already running finish; nothing new starts. A job that has already finished is returned unchanged (its status stays `done`).

## Errors

| Status | Code | When |
|---|---|---|
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |


---

# Site Map
Source: https://rankfield.dev/docs/map

List every URL of a website from its sitemaps, feeds, links and a short crawl, deduplicated, with sources and last-modified dates.

Map lists a website's URLs from what the site itself publishes and links: the sitemaps its robots.txt names, its RSS, Atom and JSON feeds, the links on its homepage, and a short crawl of its own pages.

## Pages

- [Map a website](/docs/map/map-a-site): List a website's URLs from its sitemaps, feeds, homepage links and a short crawl, each with its sources and last-modified date.
- [Start a Site Map job](/docs/map/start-a-job): Map up to 1,000 websites in one background job; each item takes the same parameters as a single call.
- [Get a Site Map job](/docs/map/get-a-job): Check a Site Map job: its status, how many items are done and failed, and when its results expire.
- [Get Site Map job results](/docs/map/get-results): Read a Site Map job's items as each one finishes, with its full answer or error, and page through them with a cursor.
- [Cancel a Site Map job](/docs/map/cancel-a-job): Stop a Site Map job. Items already finished stay readable for 24 hours; items not started are dropped.
:::


---

# Map a website
Source: https://rankfield.dev/docs/map/map-a-site

List a website's URLs from its sitemaps, feeds, homepage links and a short crawl, each with its sources and last-modified date.

`GET https://rankfield.dev/v1/map?domain={domain}`

```bash cURL
curl 'https://rankfield.dev/v1/map?domain=rankfield.dev&limit=200' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/map?domain=rankfield.dev&limit=200",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/map?domain=rankfield.dev&limit=200", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "domain": "rankfield.dev",
  "startUrl": "https://rankfield.dev/",
  "finalUrl": "https://rankfield.dev/",
  "status": 200,
  "complete": true,
  "stoppedBy": [],
  "counts": {
    "urls": 43,
    "returned": 43,
    "fromSitemaps": 8,
    "fromFeeds": 0,
    "fromLinks": 43,
    "withLastmod": 0,
    "duplicatesRemoved": 218,
    "outsideDomain": 25,
    "disallowedByRobots": 0,
    "invalid": 0,
    "notMatching": 0,
    "overCap": 0,
    "sitemapsNotRead": 0,
    "fetches": 12,
    "bytes": 528654
  },
  "sitemaps": [
    {
      "url": "https://rankfield.dev/sitemap.xml",
      "from": "robots.txt",
      "status": 200,
      "kind": "urlset",
      "urls": 8,
      "children": 0,
      "parent": null,
      "lastmod": null,
      "gzip": false,
      "bytes": 647,
      "truncated": false,
      "error": null
    }
  ],
  "feeds": [],
  "crawl": {
    "pagesFetched": 10,
    "maxPages": 10,
    "maxDepth": 1,
    "crawlDelay": null,
    "ok": 9,
    "failed": 0,
    "disallowed": 0,
    "homepage": {
      "error": null,
      "blocked": null,
      "links": 28,
      "nofollow": false
    },
    "robotsTxt": {
      "url": "https://rankfield.dev/robots.txt",
      "status": 200,
      "found": true,
      "sitemaps": 1
    }
  },
  "urls": [
    {
      "url": "https://rankfield.dev/",
      "sources": [
        "homepage",
        "sitemap",
        "crawl"
      ],
      "lastmod": null
    },
    {
      "url": "https://rankfield.dev/endpoints/",
      "sources": [
        "homepage",
        "crawl"
      ],
      "lastmod": null
    },
    {
      "url": "https://rankfield.dev/free-seo-tools/site-strength",
      "sources": [
        "homepage",
        "sitemap",
        "crawl"
      ],
      "lastmod": null
    },
    "…"
  ],
  "truncated": false,
  "timing": {
    "totalMs": 4049.8,
    "waitMs": 3812.9
  },
  "cached": false,
  "ageSeconds": 0
}
```

```json 401
{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required"
  }
}
```

Every URL comes once, in one clean spelling, and says which sources listed it and when the site last changed it, where the site says so. URLs come in the order the site presents them: the homepage, its links, each sitemap in file order, the feeds, then pages found by the crawl. The same site gives the same order every time.

Send the parameters as a query string with `GET`, or as a JSON object (up to 1 MB) with `POST` to the same path. For many domains, [start a job](/docs/map/start-a-job).

## Parameters

### Headers

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

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `domain` | string | Yes, or `url` | – | The website, such as `example.com`. `www.example.com` is read as given. Write `http://example.com` for a site without HTTPS. Send `domain` or `url`, not both. |
| `url` | string | Instead of `domain` | – | A full URL on the site; the whole site is mapped from its homepage. |
| `limit` | integer | No | `5000` | How many URLs to return, 1–50,000. Reading stops once there are this many. |
| `crawl` | integer | No | `10` | How many of the site's pages to visit for more links, besides the homepage, 0–100. |
| `subdomains` | boolean | No | `false` | `true` also keeps URLs on subdomains such as `blog.example.com`. |
| `search` | string | No | – | Only URLs containing these words, such as `pricing` or `blog 2026`. Matching pages are crawled first. |
| `sources` | string | No | `sitemaps,feeds,links` | Where to look, comma-separated: `sitemaps`, `feeds`, `links` (homepage links and the crawl). |
| `maxAge` | integer | No | `3600` | How old a stored answer may be, in seconds, up to 2,592,000. `0` maps fresh. An answer cut short by time or a busy lane is never reused. |
| `timeout` | integer | No | `30` | How long the call may take, in seconds, 1–60. |

## Response

| Field | Type | Description |
|---|---|---|
| `domain`, `startUrl` | string | The site, and the homepage address we started from. |
| `finalUrl`, `status` | string, integer \| null | The homepage after redirects, and its HTTP status. |
| `complete` | boolean | `true` when every source was read to the end. `false` when a limit stopped us; everything found is still returned. |
| `stoppedBy` | string[] | What stopped us: `limit`, `time`, `files` (100 sitemap files), `bytes` (50 MB), `fetches` or `busy`. |
| `counts` | object | `urls`, `returned`, `fromSitemaps`, `fromFeeds`, `fromLinks`, `withLastmod`, `duplicatesRemoved`, `outsideDomain`, `disallowedByRobots`, `invalid`, `notMatching`, `overCap`, `sitemapsNotRead`, `fetches`, `bytes`. |
| `sitemaps` | array | Each sitemap file: `url`, `from` (`robots.txt`, `homepage`, `guess`, `index`), `status`, `kind`, `urls`, `children`, `parent`, `lastmod`, `gzip`, `bytes`, `truncated`, `error`. |
| `feeds` | array | Each feed: `url`, `from`, `status`, `kind` (`rss`, `rdf`, `atom`, `jsonFeed`), `urls`, `bytes`, `truncated`, `error`. |
| `crawl` | object | `pagesFetched`, `maxPages`, `maxDepth`, the site's `crawlDelay`, `ok`, `failed`, `disallowed`, the `homepage` and the `robotsTxt` read. |
| `urls` | array | `{url, sources, lastmod}`. `sources`: `homepage`, `sitemap`, `feed`, `crawl`. `lastmod` is the site's own date (UTC) or `null`. |
| `truncated` | boolean | `true` when the site has more URLs than `limit`. |
| `timing` | object | `totalMs`, and `waitMs`: time spent waiting for this site's pace and for our fetch capacity. |
| `cached`, `ageSeconds` | boolean, integer | Whether this answer came from our store, and how old it is. |

## One spelling per page

Scheme and host are lowercased; default ports, `#fragments` and tracking parameters (`utm_*`, `gclid`, `fbclid`, `msclkid`, Mailchimp, HubSpot, Matomo and similar) are removed; `./` and `../` are resolved. `www.example.com` and `example.com` count as one site, written the way its homepage writes itself, and `http://` links on an HTTPS site become `https://`. When a crawled page names a `rel=canonical`, that URL is listed.

## Large sites

We read up to 100 sitemap files, 5 feeds and 50 MB per call, follow sitemap indexes 3 levels deep, and unzip `.gz` sitemaps. A site with many sitemap files can take longer than one call: the answer then has `complete: false` and `stoppedBy: ["time"]`. Call again with a longer `timeout`: the call starts over.

## How we fetch

We fetch as `Rankfield-User` (`Mozilla/5.0 (compatible; Rankfield-User/1.0; +https://rankfield.dev/bot)`), as plain HTML without running JavaScript.

- **robots.txt:** obeyed on every request and redirect, following the rules for `Rankfield-User`, or for `RankfieldBot` when the file has none for it, or `*` when it has neither. Sitemaps and pages it disallows are counted in `disallowedByRobots` and never fetched.
- **Firewalls:** a challenge, CAPTCHA or block page is reported in the answer, never worked around and never retried.
- **Never:** cookies, logins, JavaScript, proxies or other bots' names.
- **Excluded sites:** Reddit, LinkedIn, Facebook, Instagram, X/Twitter and TikTok (subdomains included), Google search result pages, and sites whose owners asked us are never fetched.
- **Pace:** each website is fetched gently, shared by all customers, slower when its robots.txt sets a `Crawl-delay` or after a slow answer. Many URLs on one site go at that site's pace.

Repeat calls to the same website within about a minute can wait their turn for that site's slot. If the wait runs past the call's time limit (30 seconds by default), the call ends with `504` `timeout` and `details.reason` `sitePace`. It doesn't count as usage: retry after `Retry-After`, or allow a longer `timeout`.

More: [Rankfield crawlers](/bot).

## Errors

Errors are `{"error": {"code", "message", "details"}}`. Branch on `code`; `message` is for people.

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | A parameter is missing, unknown or malformed. |
| 401 | `unauthorized` | No valid API key. |
| 403 | `robots_disallowed` | robots.txt disallows the homepage and nothing else on the site may be read (for example `Disallow: /`, or a robots.txt that answers with a server error). |
| 403 | `site_excluded` | The site is on the exclusion list. |
| 403 | `blocked` | The website's bot protection refused us. Reported at once and never worked around; `details` says which protection. Not counted as usage. |
| 422 | `address_not_public` | The host resolves to a private or internal address. |
| 429 | `busy` | Our fetch capacity is busy: the call was refused at once, waited 4 seconds without a turn, or its time limit ran out while it waited (then `details.reason` is `capacity`). Not counted as usage. Retry after `Retry-After` seconds. |
| 500 | `internal` | Our bug. Retry. |
| 502 | `fetch_failed` | The website could not be reached at all (DNS, connection, TLS). |
| 503 | `unavailable` | The service is restarting or briefly unavailable. Retry after `Retry-After`. (A full fetch capacity answers `429` `busy`.) |
| 504 | `timeout` | The website didn't answer within the call's time limit. When `details.reason` is `sitePace`, the call waited its turn for this website instead, which we fetch gently, shared by all customers: retry after `Retry-After`, or allow a longer `timeout`. |

A sitemap or page that fails is reported in its own entry, not as an error. Only answered calls and the `502` and website-side `504` errors count as usage; refusals, our own errors (`500`, `503`), `429` `busy` and a `504` with `details.reason` `sitePace` don't.

## Limits

No per-key limits. When the server is busy you get `429` `busy` with `Retry-After`. Waiting calls are served in turn across keys, so a key with a few calls is never stuck behind one with thousands.

## MCP

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


---

# Start a Site Map job
Source: https://rankfield.dev/docs/map/start-a-job

Map up to 1,000 websites in one background job; each item takes the same parameters as a single call.

`POST https://rankfield.dev/v1/map/jobs`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/map/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: map-2026-10-26' \
  -d '{"items":[{"domain":"rankfield.dev","limit":200},{"domain":"example.com"}]}'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/map/jobs",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": "map-2026-10-26"},
    json={"items": [{"domain": "rankfield.dev", "limit": 200}, {"domain": "example.com"}]},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/map/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "map-2026-10-26",
  },
  body: JSON.stringify({"items":[{"domain":"rankfield.dev","limit":200},{"domain":"example.com"}]}),
});
console.log(await response.json());
```

```json 202
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "queued",
    "total": 2,
    "done": 0,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": null,
    "expiresAt": null
  }
}
```

```json 409
{
  "error": {
    "code": "invalid_input",
    "message": "This Idempotency-Key was used for different items"
  }
}
```

## 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 | Yes | – | 1–200 characters you choose for this job. Sending the same key with the same body again returns the same job instead of a new one. |

### Body

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `items` | object[] | Yes | – | 1–1,000 items. Each takes the same parameters as [Map a website](/docs/map/map-a-site), as a JSON object. |

Every item is checked before the job starts. If any is invalid, the whole request is a `400` listing the first 20 (`index` and `message`).

## Response

`202` with `job`. A byte-identical body with the same `Idempotency-Key` replays the job (`200`, `Idempotency-Replayed: true`); any other body with that key is `409`.

| Field | Type | Description |
|---|---|---|
| `job.id` | string | The job id. |
| `job.status` | string | `queued`, `running`, `done` or `canceled`. |
| `job.total` | integer | Domains in the job. |
| `job.done` | integer | Items that succeeded. |
| `job.failed` | integer | Items that failed. |
| `job.createdAt`, `job.finishedAt` | string \| null | When it was created and when it finished (UTC). |
| `job.expiresAt` | string \| null | When its results are deleted: 24 hours after it finishes. |

A job runs 16 items at a time. An item counts as usage once the job accepts it, whatever its outcome. Items use the endpoint's default `timeout` rather than their own, and retry `busy` by themselves (up to 10 times). Follow it with [Get a Site Map job](/docs/map/get-a-job) and read items with [Get Site Map job results](/docs/map/get-results).

## Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | No `Idempotency-Key`, no items, too many items, or an invalid item. |
| 401 | `unauthorized` | No valid API key. |
| 409 | `invalid_input` | The `Idempotency-Key` was used before with a different body. |
| 429 | `busy` | The batch queue is full: 20,000 items from all keys are already waiting. Retry after `Retry-After` (60 seconds). |
| 503 | `unavailable` | Batch jobs are paused (storage). Retry after `Retry-After` (300 seconds). |

## Limits

Send up to 1,000 domains in one job, and as many jobs as you like. No per-key limits. Jobs from all keys share one queue: when 20,000 items are already waiting, a new job answers `429` `busy` with `Retry-After` (60 seconds).

## MCP

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


---

# Get a Site Map job
Source: https://rankfield.dev/docs/map/get-a-job

Check a Site Map job: its status, how many items are done and failed, and when its results expire.

`GET https://rankfield.dev/v1/map/jobs/{id}`

```bash cURL
curl 'https://rankfield.dev/v1/map/jobs/8f14e45fceea167a5a36dedd4bea2543' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/map/jobs/8f14e45fceea167a5a36dedd4bea2543",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/map/jobs/8f14e45fceea167a5a36dedd4bea2543", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "running",
    "total": 2,
    "done": 1,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": null,
    "expiresAt": null
  }
}
```

## 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 from [Start a Site Map job](/docs/map/start-a-job). |

## Response

| Field | Type | Description |
|---|---|---|
| `job.id` | string | The job id. |
| `job.status` | string | `queued`, `running`, `done` or `canceled`. |
| `job.total` | integer | Domains in the job. |
| `job.done` | integer | Items that succeeded. |
| `job.failed` | integer | Items that failed. |
| `job.createdAt`, `job.finishedAt` | string \| null | When it was created and when it finished (UTC). |
| `job.expiresAt` | string \| null | When its results are deleted: 24 hours after it finishes. |

Only the key that started a job can read it; any other key gets `404`.

## Errors

| Status | Code | When |
|---|---|---|
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |


---

# Get Site Map job results
Source: https://rankfield.dev/docs/map/get-results

Read a Site Map job's items as each one finishes, with its full answer or error, and page through them with a cursor.

`GET https://rankfield.dev/v1/map/jobs/{id}/results`

```bash cURL
curl 'https://rankfield.dev/v1/map/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/map/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/map/jobs/8f14e45fceea167a5a36dedd4bea2543/results?cursor=0&limit=100", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "done",
    "total": 2,
    "done": 1,
    "failed": 1,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": "2026-10-26T18:00:04Z",
    "expiresAt": "2026-10-27T18:00:04Z"
  },
  "cursor": "2",
  "hasMore": false,
  "items": [
    { "index": 0, "ok": true, "result": { "…": "the same answer as a single call" } },
    { "index": 1, "ok": false, "error": { "code": "fetch_failed", "message": "…", "details": { "reason": "dns" } } }
  ]
}
```

## 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 from [Start a Site Map job](/docs/map/start-a-job). |

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `cursor` | integer | No | `0` | Where to continue: the `cursor` of the previous answer (returned as a string; send it back as it is). |
| `limit` | integer | No | `100` | Items per answer, 1–500. |

## Read results

Start with `cursor=0`. Read `items`, then ask again with the returned `cursor` while `hasMore` is `true`. Items arrive in the order they finish; `index` is the item's position in your `items`, from 0.

| Field | Type | Description |
|---|---|---|
| `job` | object | The job, as in [Get a Site Map job](/docs/map/get-a-job). |
| `items[].index` | integer | Position in your `items`. |
| `items[].ok` | boolean | Whether the item succeeded. |
| `items[].result` | object | The same answer as [Map a website](/docs/map/map-a-site). |
| `items[].error` | object | `{code, message, details}`, as a single call's error. |
| `cursor` | string | Pass it back to continue. |
| `hasMore` | boolean | Whether more items exist now or will. |

## Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | `cursor` or `limit` is invalid. |
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |

## MCP

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


---

# Cancel a Site Map job
Source: https://rankfield.dev/docs/map/cancel-a-job

Stop a Site Map job. Items already finished stay readable for 24 hours; items not started are dropped.

`POST https://rankfield.dev/v1/map/jobs/{id}/cancel`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/map/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/map/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/map/jobs/8f14e45fceea167a5a36dedd4bea2543/cancel", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "job": {
    "id": "8f14e45fceea167a5a36dedd4bea2543",
    "status": "canceled",
    "total": 2,
    "done": 1,
    "failed": 0,
    "createdAt": "2026-10-26T18:00:00Z",
    "finishedAt": "2026-10-26T18:00:04Z",
    "expiresAt": "2026-10-27T18:00:04Z"
  }
}
```

## 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 from [Start a Site Map job](/docs/map/start-a-job). |

## Response

The job, now `canceled`, as in [Get a Site Map job](/docs/map/get-a-job). Items already running finish; nothing new starts. A job that has already finished is returned unchanged (its status stays `done`).

## Errors

| Status | Code | When |
|---|---|---|
| 401 | `unauthorized` | No valid API key. |
| 404 |  | No job with this id for this key, or it has expired. This answer has no `code`: `{"error":{"message":"Not found"}}`. |


---

# Site Audit
Source: https://rankfield.dev/docs/site-audit

Audit a whole website for technical SEO and AEO: every page checked, then joined into one link graph.

Site Audit crawls a website as Rankfield-User, from its raw HTML, and checks every page against 213 rules: broken pages and links, redirects, indexability, canonicals, sitemaps, orphan pages, titles, headings, images, duplicates, structured data, hreflang, URL hygiene, security headers, mobile, social cards and AI-crawler access. Then it joins the pages into a link graph for the site-wide checks: click depth, inlinks, internal link score, orphans, redirect chains, duplicates, hreflang return links and sitemap consistency.

An audit runs in the background. Start it with `POST /v1/site-audit`, follow its progress, and read its results while it crawls and after.

## Pages

- [Audit a website](/docs/site-audit/audit-a-website): Start a technical SEO and AEO audit of a website: we crawl its pages and check each one against 213 rules.
- [Follow an audit](/docs/site-audit/follow-an-audit): Read an audit's status and live progress: pages fetched, the current speed, the site's response time and the issues found so far.
- [Read the results](/docs/site-audit/read-the-results): Read what an audit found: the main problems, every issue with its pages, page and link records, the folder tree, the crawl log and earlier audits.
:::


---

# Audit a website
Source: https://rankfield.dev/docs/site-audit/audit-a-website

Start a technical SEO and AEO audit of a website: we crawl its pages and check each one against 213 rules.

`POST https://rankfield.dev/v1/site-audit`

```bash cURL
curl -X POST 'https://rankfield.dev/v1/site-audit' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"domain":"shop.example"}'
```

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/site-audit",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"domain": "shop.example"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/site-audit", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"domain":"shop.example"}),
});
console.log(await response.json());
```

```json 200
{
  "audit": {
    "id": "1414774bd14c096e08ec5b95fc183bcf",
    "domain": "https://shop.example",
    "status": "queued",
    "createdAt": "2026-10-28T20:45:39Z",
    "startedAt": null,
    "finishedAt": null,
    "expiresAt": null,
    "stoppedBy": [],
    "error": null,
    "options": {
      "domain": "https://shop.example",
      "maxPages": 10000,
      "subdomains": false,
      "sources": [
        "links",
        "sitemaps"
      ],
      "urls": [],
      "mode": "full",
      "sample": false,
      "samplePerTemplate": 500,
      "checkExternal": true,
      "checkResources": true,
      "previous": null,
      "speed": null
    },
    "progress": {
      "phase": "queued"
    },
    "counts": {}
  }
}
```

```json 401
{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required"
  }
}
```

The call answers at once (`200`, `status: "queued"`) with the audit's `id`; the crawl runs in the background. [Follow it](/docs/site-audit/follow-an-audit), then [read the results](/docs/site-audit/read-the-results), during the crawl or after. Big sites take time: a site that answers fast is crawled at up to 50 pages a second, a slow or struggling one at 2.

## Parameters

Send a JSON object.

### Headers

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

### Body

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `domain` | string | Yes, or `url` | – | The site: a host such as `example.com`, or a URL whose host is used. `https` unless written `http://`. |
| `maxPages` | integer | No | `10000` | HTML pages to fetch at most, 1 to 5,000,000. |
| `subdomains` | boolean | No | `false` | Also crawl subdomains such as `blog.example.com`. |
| `sources` | string[] | No | `["links","sitemaps"]` | Where URLs come from: `links` (a crawl from the homepage), `sitemaps` (robots.txt's sitemaps, else `/sitemap.xml`), `urls` (your `urls` list). |
| `urls` | string[] | No | – | Up to 10,000 URLs of the site you know exist, from Search Console, analytics or logs: fetched, and used to find orphan pages. |
| `mode` | string | No | `full` | `full`: content and links. `status`: only the status of every URL in the sitemaps and `urls` (no content): broken pages and redirect chains in minutes. |
| `sample` | boolean | No | `false` | Audit at most `samplePerTemplate` pages per URL template and estimate the rest, for very large sites. |
| `samplePerTemplate` | integer | No | `500` | Pages per template when `sample` is true, 10 to 10,000. |
| `checkExternal` | boolean | No | `true` | Check each distinct external link target once, at most 2,000 per audit. |
| `checkResources` | boolean | No | `true` | Check each distinct image, script and stylesheet of the site once, at most 2,000 per audit. |
| `previous` | string | No | – | The `id` of an earlier finished audit of the same site: unchanged pages reuse its records, and [diff](/docs/site-audit/read-the-results) compares the two. |
| `speed` | integer | No | – | The most fetches a second, 2 to 50. By default the speed adapts to the site, up to 50. |

## Response

`200` with the audit, the same object [Follow an audit](/docs/site-audit/follow-an-audit) reads:

| Field | Type | Description |
|---|---|---|
| `audit.id` | string | The audit's id: keep it to read the audit. |
| `audit.domain` | string | The site, as we crawl it (`https://example.com`). |
| `audit.status` | string | `queued`, `running`, `postPass` (the site-wide checks), `done`, `canceled` or `failed`. |
| `audit.options` | object | The parameters as we read them, defaults filled in. |
| `audit.progress`, `audit.counts` | object | Pages fetched so far, the speed and the issues found: see [Follow an audit](/docs/site-audit/follow-an-audit). |
| `audit.createdAt`, `audit.startedAt`, `audit.finishedAt`, `audit.expiresAt` | string \| null | When it was created, started and finished, and when its results are deleted (30 days after it ends), in UTC. |
| `audit.stoppedBy` | string[] | Why it ended early: `maxPages`, `siteErrors`, `rateLimited` (the site kept rate-limiting us for most of ten minutes), `canceled` or `time`; empty when it crawled everything it found. |
| `audit.queuePosition` | integer | Its place in the queue, while `queued`. |

## How we crawl

We fetch as `Rankfield-User` (`Mozilla/5.0 (compatible; Rankfield-User/1.0; +https://rankfield.dev/bot)`), as plain HTML without running JavaScript.

- **Speed:** each audit adapts to its site. It starts at 5 fetches a second and climbs, up to 50, while the site answers quickly and without errors. At the first sign of strain (a `429`, a `503`, another `5xx`, a connection error or a slower answer) it halves at once and honours `Retry-After`, never going below 2 a second, and pauses for a minute after three `5xx` in a row. A site that keeps failing (more than half of its last 200 answers) stops the audit with `stoppedBy: ["siteErrors"]`; what was found is kept. The limits are the same for every site.
- **A site that rate-limits us:** each `429` or `503` halves the speed, and we leave the site alone for as long as its `Retry-After` asks (30 seconds when it gives none, 5 minutes at most). While we wait, [progress](/docs/site-audit/follow-an-audit) shows `siteHold` and gives no time estimate. A site that holds us for most of ten minutes stops the audit with `stoppedBy: ["rateLimited"]`; what was found is kept, the site-wide checks run on it, and the summary's `notes` say so.
- **robots.txt and `Crawl-delay`:** obeyed on every request, for `Rankfield-User`, or for `RankfieldBot` when the file has none for it, or `*` when it has neither.
- **Redirects:** not followed blindly. Each hop is fetched and recorded on its own, so chains and loops are exact, and robots.txt is checked on every hop.
- **Other sites:** a link, redirect or resource that leaves the site gets one status check (`checkExternal`) and is never crawled. Cloudflare's own `/cdn-cgi/` paths are never fetched.
- **Not checked is never broken:** an external URL we did not check is never counted as a broken link: a site we never fetch (below), one robots.txt disallows, or one whose bot protection refused our check (a `401`, `403` or `429`, or a challenge page). They are listed with `status=unchecked` and counted in `counts.inventory.externalUnchecked`.
- **Never:** cookies, logins, JavaScript, proxies or other bots' names. A firewall page is reported, never worked around. Reddit, LinkedIn, Facebook, Instagram, X/Twitter and TikTok (subdomains included), Google search result pages and sites whose owners asked us are never fetched.
- **What we keep:** each page's record (status, headers of interest, title, description and h1 cut to 200 characters, counts, hashes) and its links; never the page's text. Results are kept 30 days after the audit ends.

More: [Rankfield crawlers](/bot).

## Errors

Errors are `{"error": {"code", "message", "details"}}`. Branch on `code`; `message` is for people.

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | A parameter is missing, unknown or malformed (unknown parameters are refused), or the body is over 1 MB. |
| 401 | `unauthorized` | No valid API key. |
| 403 | `site_excluded` | The site is on the exclusion list. |
| 404 | `not_found` | No audit with this id for this key (only the key that started an audit can read it), an unknown issue, or a page that is not in the audit. |
| 422 | `address_not_public` | The host resolves to a private or internal address. |
| 429 | `busy` | The audit queue is full: 64 audits already wait (`details.reason` `capacity`). Not counted as usage. Retry after `Retry-After` seconds. |
| 500 | `internal` | Our bug. Retry. |
| 503 | `unavailable` | New audits are paused while the service is short of storage, or it is restarting. Retry after `Retry-After`. |

## Limits

No per-key limits. Up to 8 audits crawl at once and the rest wait in order; when 64 already wait, a new audit answers `429` `busy` with `Retry-After`. At most one audit over 1,000,000 pages runs at a time and 2 more wait; another one answers `429` `busy` with `Retry-After`, and smaller audits can start ahead of a waiting one. An audit fetches at most 5,000,000 pages.

## MCP

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


---

# Follow an audit
Source: https://rankfield.dev/docs/site-audit/follow-an-audit

Read an audit's status and live progress: pages fetched, the current speed, the site's response time and the issues found so far.

`GET https://rankfield.dev/v1/site-audit/{id}`

```bash cURL
curl 'https://rankfield.dev/v1/site-audit/169c615ff6c5057c8ca5384a6e2df47a' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/site-audit/169c615ff6c5057c8ca5384a6e2df47a",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/site-audit/169c615ff6c5057c8ca5384a6e2df47a", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "audit": {
    "id": "169c615ff6c5057c8ca5384a6e2df47a",
    "domain": "https://rankfield.dev",
    "status": "done",
    "createdAt": "2026-10-28T21:47:08Z",
    "startedAt": "2026-10-28T21:47:08Z",
    "finishedAt": "2026-10-28T21:48:53Z",
    "expiresAt": "2026-11-27T21:48:53Z",
    "stoppedBy": [],
    "error": null,
    "options": {
      "domain": "https://rankfield.dev",
      "maxPages": 200,
      "subdomains": false,
      "sources": [
        "links",
        "sitemaps"
      ],
      "urls": [],
      "mode": "full",
      "sample": false,
      "samplePerTemplate": 500,
      "checkExternal": false,
      "checkResources": true,
      "previous": null,
      "speed": 2.0
    },
    "progress": {
      "phase": "done",
      "fetched": 199,
      "queued": 0,
      "known": 361,
      "pagesPerSecond": 1.9,
      "rate": 2.0,
      "ttfbP50Ms": 63.0,
      "baselineMs": 54.0,
      "errors": 0,
      "halvings": 0,
      "pauses": 0,
      "etaSeconds": 0,
      "siteHold": null,
      "rateLimited": 0,
      "stoppedBy": [],
      "issues": {
        "error": 0,
        "warning": 10,
        "notice": 464
      }
    },
    "counts": {
      "inventory": {
        "internal": 202,
        "htmlPages": 103,
        "indexable": 103,
        "documents": 96,
        "redirects": 0,
        "errors": 0,
        "resources": 3,
        "disallowed": 0,
        "notFetched": 0,
        "known": 199,
        "sitemapUrls": 99,
        "externalChecked": 0,
        "externalBroken": 0,
        "externalUnchecked": {
          "total": 0,
          "excluded": 0,
          "robotsDisallowed": 0,
          "botBlocked": 0
        },
        "byStatus": {
          "2xx": 202,
          "3xx": 0,
          "4xx": 0,
          "5xx": 0,
          "failed": 0
        }
      },
      "health": {
        "score": 100,
        "urlsWithErrors": 0,
        "urlsWithoutErrors": 202,
        "internalUrls": 202,
        "note": "The share of crawled internal URLs with no error-level issue; site-wide findings are not counted per URL."
      },
      "issues": {
        "error": {
          "issueTypes": 0,
          "affectedUrls": 0
        },
        "warning": {
          "issueTypes": 4,
          "affectedUrls": 10
        },
        "notice": {
          "issueTypes": 18,
          "affectedUrls": 464
        }
      },
      "byRule": {
        "canonical-missing": 7,
        "not-in-sitemap": 4,
        "empty-anchor": 3,
        "low-link-score": 7,
        "title-too-short": 33,
        "title-duplicate": 3,
        "title-same-as-h1": 1,
        "description-too-long": 1,
        "description-too-short": 1,
        "description-duplicate": 3,
        "h1-duplicate": 3,
        "heading-empty": 2,
        "img-too-large": 1,
        "thin-content": 1,
        "low-text-ratio": 54,
        "duplicate-content": 3,
        "schema-none": 103,
        "url-uppercase": 1,
        "no-hsts": 103,
        "og-missing": 9,
        "twitter-card-missing": 28,
        "no-preferred-image": 103
      },
      "byRuleIndexable": {
        "heading-empty": 2,
        "not-in-sitemap": 4,
        "title-same-as-h1": 1,
        "low-text-ratio": 54,
        "no-hsts": 103,
        "og-missing": 9,
        "url-uppercase": 0,
        "description-too-short": 1,
        "description-too-long": 1,
        "title-too-short": 33,
        "img-too-large": 1,
        "title-duplicate": 3,
        "schema-none": 103,
        "duplicate-content": 3,
        "description-duplicate": 3,
        "thin-content": 1,
        "twitter-card-missing": 28,
        "no-preferred-image": 103,
        "h1-duplicate": 3,
        "low-link-score": 7,
        "empty-anchor": 3,
        "canonical-missing": 7
      },
      "links": 7267,
      "sitemaps": 1,
      "fetched": 199
    }
  }
}
```

```json 404
{
  "error": {
    "code": "not_found",
    "message": "Not found"
  }
}
```

Poll every few seconds while `status` is `queued`, `running` or `postPass`. Issue counts are live, and every [result](/docs/site-audit/read-the-results) can be read during the crawl.

## 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 audit's `id`, from [Audit a website](/docs/site-audit/audit-a-website). |

## Response

| Field | Type | Description |
|---|---|---|
| `audit` | object | As [Audit a website](/docs/site-audit/audit-a-website) answers. |
| `audit.progress.phase` | string | `queued`, `probes` (robots.txt, the homepage, how the site answers a page that does not exist, its http and www variants, llms.txt), `crawl` (sitemaps, pages and resources), `postPass` (the site-wide checks) or `done`. |
| `audit.progress.fetched`, `audit.progress.queued`, `audit.progress.known` | integer | Pages fetched, waiting, and known so far. |
| `audit.progress.pagesPerSecond`, `audit.progress.rate` | number | Pages fetched a second, and the speed the brake allows now (fetches a second). |
| `audit.progress.ttfbP50Ms`, `audit.progress.baselineMs` | number \| null | The site's median time to first byte now, and at the start: a slower site slows the audit. |
| `audit.progress.errors`, `audit.progress.halvings`, `audit.progress.pauses` | integer | Failed fetches, and how often the speed was halved or the crawl paused for the site's sake. |
| `audit.progress.etaSeconds` | integer \| null | An estimate of the time left: the pages still to fetch (up to `maxPages` of those known so far) at the current speed. `null` while the site makes us wait. |
| `audit.progress.siteHold` | object \| null | While the site makes us wait: `{until, seconds, reason, status}`. `reason` is `rateLimited` (it answered `429` or `503`, and `status` says which; we wait for its `Retry-After`, 30 seconds when it gives none, 5 minutes at most) or `siteErrors` (we paused after errors). `until` is when we go on, in Unix milliseconds, and `seconds` how long that is from now. |
| `audit.progress.rateLimited` | integer | How many times the site answered `429` or `503`. |
| `audit.progress.issues`, `audit.counts.issues` | object | Issues found so far, per severity (`error`, `warning`, `notice`): `issueTypes`, the kinds of issue, and `affectedUrls`, URL–issue pairs (a URL with three issues counts three times). |
| `audit.counts.health` | object | `{score, urlsWithErrors, urlsWithoutErrors, internalUrls}`: the health score, the share of crawled internal URLs with no error-level issue, 0 to 100, with its parts. Site-wide findings don't count per URL. |
| `audit.counts.inventory` | object | What was crawled, apart from issues: `internal` (every crawled URL of the site), `htmlPages` (HTML pages that answered 200), `indexable`, `documents` (Markdown, PDF and other files, which are not HTML pages), `redirects`, `errors`, `resources` (the site's images, scripts and stylesheets), `disallowed` (by robots.txt), `notFetched`, `known`, `sitemapUrls`, `externalChecked` (external URLs given a status check), `externalBroken` (the broken ones), `externalUnchecked` (`{total, excluded, robotsDisallowed, botBlocked}`: external URLs we did not check, on sites we never fetch, disallowed by robots.txt, or refused by bot protection, never counted as broken) and `byStatus`. |

## Your audits

`GET /v1/site-audit` lists the audits your key started, newest first, each as above.

## Stop an audit

`POST /v1/site-audit/{id}/cancel` stops the crawl. What was found stays readable, and the site-wide checks run on it (`stoppedBy: ["canceled"]`).

## Errors

| Status | Code | When |
|---|---|---|
| 401 | `unauthorized` | No valid API key. |
| 404 | `not_found` | No audit with this id for this key (only the key that started an audit can read it), an unknown issue, or a page that is not in the audit. |
| 500 | `internal` | Our bug. Retry. |
| 503 | `unavailable` | New audits are paused while the service is short of storage, or it is restarting. Retry after `Retry-After`. |

## MCP

On the [MCP server](/docs/agents/mcp-server), the tools for this are `site_audit_list`, `site_audit_status` and `site_audit_cancel`.


---

# Read the results
Source: https://rankfield.dev/docs/site-audit/read-the-results

Read what an audit found: the main problems, every issue with its pages, page and link records, the folder tree, the crawl log and earlier audits.

`GET https://rankfield.dev/v1/site-audit/{id}/summary`

```bash cURL
curl 'https://rankfield.dev/v1/site-audit/169c615ff6c5057c8ca5384a6e2df47a/summary' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/site-audit/169c615ff6c5057c8ca5384a6e2df47a/summary",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/site-audit/169c615ff6c5057c8ca5384a6e2df47a/summary", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "id": "169c615ff6c5057c8ca5384a6e2df47a",
  "domain": "https://rankfield.dev",
  "status": "done",
  "health": {
    "score": 100,
    "urlsWithErrors": 0,
    "urlsWithoutErrors": 202,
    "internalUrls": 202,
    "note": "The share of crawled internal URLs with no error-level issue; site-wide findings are not counted per URL."
  },
  "inventory": {
    "internal": 202,
    "htmlPages": 103,
    "indexable": 103,
    "documents": 96,
    "redirects": 0,
    "errors": 0,
    "resources": 3,
    "disallowed": 0,
    "notFetched": 0,
    "known": 199,
    "sitemapUrls": 99,
    "externalChecked": 0,
    "externalBroken": 0,
    "externalUnchecked": {
      "total": 0,
      "excluded": 0,
      "robotsDisallowed": 0,
      "botBlocked": 0
    },
    "byStatus": {
      "2xx": 202,
      "3xx": 0,
      "4xx": 0,
      "5xx": 0,
      "failed": 0
    }
  },
  "notes": [],
  "headline": "Health 100 of 100: 202 of 202 crawled URLs have no errors. 103 HTML pages, 96 other documents; 0 kinds of error, 22 issue types in all.",
  "top": [
    {
      "issue": "schema-none",
      "name": "No structured data",
      "group": "ai",
      "severity": "notice",
      "site": false,
      "urls": 103,
      "of": {
        "set": "indexable",
        "urls": 103,
        "label": "indexable pages"
      },
      "share": 100.0,
      "text": "No structured data: 103 of 103 indexable pages. The indexable page has no structured data. Add JSON-LD for the page's type (Article, Product, Organization, BreadcrumbList…).",
      "example": "https://rankfield.dev/"
    },
    {
      "issue": "no-hsts",
      "name": "HSTS missing",
      "group": "other",
      "severity": "notice",
      "site": false,
      "urls": 103,
      "of": {
        "set": "htmlPages",
        "urls": 103,
        "label": "HTML pages"
      },
      "share": 100.0,
      "text": "HSTS missing: 103 of 103 HTML pages. The HTTPS page sends no Strict-Transport-Security header. Send HSTS (max-age of at least six months) once the whole site is HTTPS.",
      "example": "https://rankfield.dev/"
    },
    {
      "issue": "no-preferred-image",
      "name": "No preferred image",
      "group": "social",
      "severity": "notice",
      "site": false,
      "urls": 103,
      "of": {
        "set": "htmlPages",
        "urls": 103,
        "label": "HTML pages"
      },
      "share": 100.0,
      "text": "No preferred image: 103 of 103 HTML pages. The page names no preferred image (og:image, or an image in its structured data). Name the page's main image, so search and AI results can show it.",
      "example": "https://rankfield.dev/"
    },
    "…"
  ]
}
```

Start with the summary: its `notes` say how complete the audit is (why the crawl stopped early, rate limiting, the external URLs we did not check), then the ten most important problems in plain words, each with the pages it affects, how to fix it and an example. Then go as deep as you need. Every call works during the crawl too, on what was found so far.

## 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 audit's `id`, from [Audit a website](/docs/site-audit/audit-a-website). |

## Every way to read an audit

| Call | Answer |
|---|---|
| `GET /v1/site-audit` | Your audits, newest first. |
| `GET /v1/site-audit/{id}` | Status, live `progress` and `counts`. See [Follow an audit](/docs/site-audit/follow-an-audit). |
| `GET …/{id}/summary` | `notes`, plain sentences on how complete the audit is (why the crawl stopped early, rate limiting, the external URLs we did not check), then the ten most important problems in plain words. |
| `GET …/{id}/issues` | Every issue found, worst first, with the report's `groups` in order (Internal pages, Indexability, AI discoverability, Links, Redirects, Content and so on, each with its `subgroups`). Each issue: `id`, a short `name` such as "404 page", `severity`, `group`, `groupName`, `subgroup`, `description`, `fix`, `urls` out of `of`, `share`, `indexable` and `notIndexable`, `site` for site-wide findings, `found`, `change` against an earlier audit, `history` and five `examples`. In Links and Content a page issue comes as two rows, Indexable and Not indexable (`split`); `split=none` gives one row per issue, `split=indexability` splits every group. `view=all` lists all 213 checks, those that found nothing with `found: false`. Filters `severity`, `group`; `compare` names another finished audit of the same site to compare with. |
| `GET …/{id}/issues/{issue}` | The URLs with one issue as a table: `columns` names its fields in order, `url`, `status`, `depth`, `indexable` and `inlinks`, then the issue's own (`title` and `titleLength` for title issues, `redirectTo`, `canonical`, `ttfbMs`…), then `detail`. Each URL also has its `template`, and `total` counts them. Against an earlier audit a URL may carry `mark` (`new` or `added`); `lost=true` lists the URLs that no longer have it, marked `removed` or `missing`; `compare` as for `…/issues`. |
| `GET …/{id}/pages` | Page records. Filters `kind` (page, resource, external, all), `status` (a code, a class such as `4xx`, `failed`, `blocked`, `broken`, or `unchecked`: external URLs we did not check), `type` (html, document, image, css, js), `indexable`, `noindex`, `nofollow`, `canonical` (self, other, none), `orphan`, `template`, `depth`, `minDepth`, `maxInlinks`, `minWords`, `maxWords`, `issue` and `q` (the URL contains it); `sort` (url, status, depth, inlinks, words, ttfb, bytes, title) with `order` (asc, desc); `total` counts every match. `url` gives one page with its issues, inlinks and outlinks. |
| `GET …/{id}/pages/filters` | Ready-made page lists with their counts, in groups: internal URLs by status, resources, external URLs (all, broken, not checked), content type, indexability, canonical, depth and links. Each has `params`: send them as the query of `…/pages` to list it. |
| `GET …/{id}/links` | Links, each with `type` (href, image, resource, redirect), `flags`, `sourceStatus`, `targetStatus` and `targetNotCrawled`, and `total`. Filters `q` (either URL contains it), `from`, `to`, `broken`, `external`, `nofollow`, `resources`, `status` (of the target: `2xx` to `5xx`, `failed`, `blocked`, `unchecked`, `notCrawled`) and `type` (image, resource, navigation, redirect). |
| `GET …/{id}/links/filters` | Ready-made link lists with their counts: all, internal, external and to resources; internal links by the status of their target; external links to a broken URL or to one we did not check; followed, nofollow, image, navigation and redirect hops. Each has `params` for `…/links`. |
| `GET …/{id}/structure` | The site as a folder tree: the folders under `path` (none for the hosts), each with `urls`, `hasChildren` and `dist`, its URLs spread by `by`: `status` (the default), `type`, `depth` or `indexability`. |
| `GET …/{id}/log` | The crawl log: `from`, `to`, `durationSeconds` and `urls`, `minutes` (each minute's URLs by status class and fetches a second) and the `latest` fetches. |
| `GET …/{id}/history` | Every audit of the same site by your key, newest first, with its `health` score, `urls`, `htmlPages`, `resources`, `urlsWithErrors` and issues per severity. |
| `GET …/{id}/redirects` | Redirects with their whole chain and the final status; `chains=true` for chains only. |
| `GET …/{id}/duplicates` | Groups of exact duplicates (body, title, description, h1) and near duplicates; filter `kind`. |
| `GET …/{id}/orphans` | Pages known from your sitemaps or `urls` that no followed internal link reaches, with where we know them from. |
| `GET …/{id}/templates` | URL templates (`/blog/{slug}`) with page counts and their issues; estimates for sampled audits. |
| `GET …/{id}/sitemaps` | Each sitemap file read, and the consistency checks. |
| `GET …/{id}/diff/{previousId}` | New and fixed issues, new and gone pages, changed titles, canonicals and status, against an earlier audit of the site. |
| `GET …/{id}/export` | Every page record, 1,000 at a time, by `cursor`. |
| `POST …/{id}/cancel` | Stops the crawl. What was found stays readable, and the site-wide checks run on it. |

Lists take `cursor` (from the previous answer) and `limit` (1 to 1,000, default 100), and answer `{cursor, hasMore, items}`: pass `cursor` back while `hasMore` is true.

## The pages behind one issue

`GET /v1/site-audit/{id}/issues/title-duplicate`, from an audit of rankfield.dev: the `?tab=` addresses repeat the homepage's title.

```json
{
  "cursor": null,
  "hasMore": false,
  "items": [
    {
      "url": "https://rankfield.dev/",
      "status": 200,
      "depth": 0,
      "indexable": true,
      "inlinks": 102,
      "title": "Rankfield — Open web link metrics",
      "titleLength": 33,
      "detail": "3 pages",
      "template": "/"
    },
    {
      "url": "https://rankfield.dev/?tab=key",
      "status": 200,
      "depth": 2,
      "indexable": true,
      "inlinks": 99,
      "title": "Rankfield — Open web link metrics",
      "titleLength": 33,
      "detail": "3 pages",
      "template": "/?tab={v}"
    },
    {
      "url": "https://rankfield.dev/?tab=strength",
      "status": 200,
      "depth": 2,
      "indexable": true,
      "inlinks": 3,
      "title": "Rankfield — Open web link metrics",
      "titleLength": 33,
      "detail": "3 pages",
      "template": "/?tab={v}"
    }
  ],
  "issue": {
    "id": "title-duplicate",
    "name": "Duplicate title",
    "severity": "warning",
    "group": "content",
    "groupName": "Content",
    "subgroup": "",
    "description": "Several indexable pages share this exact title.",
    "fix": "Give each page its own title."
  },
  "of": {
    "set": "indexable",
    "urls": 103,
    "label": "indexable pages"
  },
  "total": 3,
  "columns": [
    "url",
    "status",
    "depth",
    "…"
  ],
  "compared": true
}
```

## Severity

- **error** (45 rules): hurts indexing or visitors now, such as a page or internal link that answers 4xx or 5xx, a redirect loop, or a canonical that points at a broken page.
- **warning** (78 rules): likely costs traffic, such as duplicate pages, thin content, orphan pages, or a linked page served as something other than HTML.
- **notice** (90 rules): worth a look, such as missing structured data, short titles or missing social cards.

## How counts read

- **Names and groups.** Each issue has a short `name` ("404 page", "Title too long"), a `description` of what was found and a `fix`, and sits in a `group` of the report, sometimes in a `subgroup`.
- **URLs affected.** An issue's `urls` counts each URL that has it once, out of the set the rule reads, given in `of` (`{set, urls, label}`): every crawled URL of the site (`internal`), HTML pages that answered 200 (`htmlPages`), the indexable ones (`indexable`), `redirects`, `sitemapUrls`, or the whole site (`site`, with no URL count). Read it as "3 of 103 HTML pages". `share` is the same as a percentage and never passes 100.
- **Documents are not HTML pages.** Markdown, PDF and other files count in the inventory's `documents` and only in the `internal` set.
- **Indexable split.** Page issues give `indexable` and `notIndexable`, so you can tell the pages that matter for search apart.
- **Issues found.** Per severity, `issueTypes` is how many kinds of issue were found and `affectedUrls` how many URL–issue pairs: a URL with three issues counts three times.
- **Health score.** The share of crawled internal URLs with no error-level issue, 0 to 100, given with its parts in `counts.health`.
- **Change.** Against an earlier finished audit of the same site (`compare` when you name one, else `previous`, else your latest one), each issue gives `change`: `added` (crawled both times, has it now and didn't), `new` (first crawled now and has it), `removed` (had it and doesn't), `missing` (had it and wasn't crawled this time) and `net`. An issue that is gone shows `urls` 0.
- **History.** `history` gives the issue's `urls` in up to ten earlier finished audits of the site, oldest first, ending with this one.
- **Not checked is never broken.** An external URL we did not check carries `error`: `siteExcluded` (a site we never fetch, such as the social networks' share links), `robotsDisallowed`, or `botBlocked` (its bot protection answered our check with a `401`, `403` or `429`, or a challenge page; `facts.firewall` says what we saw). None of them counts as a broken link, in issues, the `broken` filters or the inventory. `status=unchecked` lists them, on `…/pages` and `…/links`.

## Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | A parameter is missing, unknown or malformed (unknown parameters are refused), or the body is over 1 MB. |
| 401 | `unauthorized` | No valid API key. |
| 404 | `not_found` | No audit with this id for this key (only the key that started an audit can read it), an unknown issue, or a page that is not in the audit. |
| 500 | `internal` | Our bug. Retry. |
| 503 | `unavailable` | New audits are paused while the service is short of storage, or it is restarting. Retry after `Retry-After`. |

## MCP

On the [MCP server](/docs/agents/mcp-server), the tools for this are `site_audit_summary`, `site_audit_issues`, `site_audit_issue_pages`, `site_audit_pages`, `site_audit_links`, `site_audit_redirects`, `site_audit_duplicates`, `site_audit_orphans`, `site_audit_templates`, `site_audit_sitemaps`, `site_audit_diff`, `site_audit_export`, `site_audit_page_filters`, `site_audit_link_filters`, `site_audit_structure`, `site_audit_log` and `site_audit_history`.


---

# AI agents
Source: https://rankfield.dev/docs/agents

Connect AI agents to Rankfield: the MCP server, the agent skill, llms.txt and Markdown copies of every docs page.

Agents can use Rankfield three ways: call the HTTP API directly, connect to the MCP server, or follow the agent skill. Every docs page also has a Markdown copy, and `/llms.txt` lists them all.

## Pages

- [For coding agents](/docs/agents/for-coding-agents): The short version of the Rankfield docs for coding agents: base URL, auth, the endpoint to pick for each task, timeouts and gotchas.
- [MCP server](/docs/agents/mcp-server): Connect Claude, Cursor or any MCP client to Rankfield's remote MCP server over Streamable HTTP, with your API key as a bearer token.
- [Agent skill](/docs/agents/agent-skill): Give an AI agent Rankfield's SKILL.md: when to use Rankfield, how to get a key, and the calls to make, in one file.
- [llms.txt and Markdown pages](/docs/agents/llms-txt-and-markdown): Read the Rankfield docs as plain Markdown: llms.txt, llms-full.txt, a .md copy of every page, and Accept: text/markdown.
:::


---

# For coding agents
Source: https://rankfield.dev/docs/agents/for-coding-agents

The short version of the Rankfield docs for coding agents: base URL, auth, the endpoint to pick for each task, timeouts and gotchas.

Read this page first when you write code against Rankfield. Every link has a Markdown copy: add `.md` to the URL, or send `Accept: text/markdown`. The full index is [llms.txt](/llms.txt); everything in one file is [llms-full.txt](/llms-full.txt).

## Basics

- Base URL: `https://rankfield.dev/v1/`. JSON in, JSON out.
- Auth: `Authorization: Bearer <key>` on every request. One key works everywhere. Keys start with `ls_` and do not expire.
- No key yet: `POST https://rankfield.dev/v1/keys` with the header `Origin: https://rankfield.dev` returns one in `key`. Never print it or commit it.
- No SDK: use any HTTP client. No CORS: call from a server or script, not browser JavaScript.

## Pick the endpoint

| Task | Request |
|---|---|
| How strong is a domain's link profile? | `GET /v1/domains/{domain}/site-strength` |
| How many domains link to it, and the strongest 20? | `GET /v1/domains/{domain}/referring-domains` |
| Every domain that links to it | `GET /v1/domains/{domain}/referrers`, follow `nextCursor` |
| Every domain it links to | `GET /v1/domains/{domain}/outbound-domains` |
| A huge list as a file | `POST /v1/jobs` `{"kind":"referrers-export","domain":"…"}` |
| The links on a live page | `GET /v1/html/link-extraction?url=…` |
| A page as Markdown with metadata, links and structured data | `GET /v1/scrape?url=…` |
| The language of a live page | `GET /v1/scrape?url=…&include=language` |
| Which crawlers and AI bots may read a page | `GET /v1/bot-view?url=…` |
| A company's logo, colours and fonts | `GET /v1/brand?domain=…` |
| Every URL of a site | `GET /v1/map?domain=…` |
| Bing autocomplete for a keyword | `GET /v1/bing/suggest?query=…` |
| DuckDuckGo autocomplete | `GET /v1/ddg/suggest?query=…` |
| Yahoo search predictions | `GET /v1/yahoo/search-predictions?query=…` |

For more than a handful of URLs or keywords, use the endpoint's `/jobs` path: see [Batch jobs](/docs/get-started/batch-jobs).

## Timeouts

| Request | Typical time | Client timeout |
|---|---|---|
| Site Strength, referring domains, lists, profile | Under 1 second | 10 seconds |
| Export jobs | Seconds to minutes, by list size | Poll every 5 seconds |
| Link Extraction (one page) | A few seconds | 90 seconds (the request waits up to `wait`, 60 by default) |
| Suggest (one keyword) | Under 1 second | 15 seconds |
| Scrape, Bot View and Brand | A few seconds | `timeout` + 5 seconds (20 by default) |
| Map | Seconds; large sites longer | `timeout` + 5 seconds (30 by default) |

## Gotchas

- `null` means unknown, never zero. Keep it as missing data.
- `"inGraph": false` (with zeros) from the graph endpoints means the domain isn't in our link graph yet: not "site offline", and not a measured zero. The field is absent otherwise; a malformed domain gets `400`.
- A website's own `404` or `500` is not an error from us: it is in the answer's `status` field (or a `422` for the page endpoints).
- Error bodies differ by family: `error` is an object with `message` (and `code` on newer endpoints), or a string on the suggest endpoints. Read `typeof body.error === "string" ? body.error : body.error.message`.
- Retry only `429`, `503`, `504` (after `Retry-After`) and `502`. See [Errors](/docs/get-started/errors).
- Page endpoints read HTML without running JavaScript. Pages built by scripts show little content; that is the page, not a bug.
- Job results arrive in completion order. Use `position` or `index` to match them to your input.
- Cursors are opaque. Pass them back unchanged, with the same filters.


---

# MCP server
Source: https://rankfield.dev/docs/agents/mcp-server

Connect Claude, Cursor or any MCP client to Rankfield's remote MCP server over Streamable HTTP, with your API key as a bearer token.

The server is a thin layer over the HTTP API: each tool calls the same endpoint with your key and returns its JSON.

## Connect

- URL: `https://rankfield.dev/mcp`
- Transport: Streamable HTTP (JSON-RPC over `POST`), protocol versions `2025-11-25`, `2025-06-18` and `2025-03-26`.
- Auth: the header `Authorization: Bearer <key>`. Every call needs it, `tools/list` included.

For a client configured with JSON:

```json
{
  "mcpServers": {
    "rankfield": {
      "type": "http",
      "url": "https://rankfield.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

With Claude Code:

```bash
claude mcp add --transport http rankfield https://rankfield.dev/mcp --header "Authorization: Bearer YOUR_API_KEY"
```

Opening the URL in a browser shows connection instructions; tools only answer authenticated `POST` requests.

## Tools

| Tool | What it does | Same as |
|---|---|---|
| `get_site_strength` | Site Strength of a domain | [Get Site Strength](/docs/site-strength/get-site-strength) |
| `get_referring_domains` | Count and top 20 referring domains | [Get Referring Domains](/docs/referring-domains/get-referring-domains) |
| `list_referring_domains` | Every referring domain, with `cursor` | [List All Referring Domains](/docs/referring-domains/list-referrers) |
| `list_outbound_domains` | Every domain it links to | [List Outbound Domains](/docs/referring-domains/list-outbound-domains) |
| `get_referrer_profile` | Referring domains per Site Strength range | [Get Referrer Profile](/docs/referring-domains/get-referrer-profile) |
| `start_domain_export` | Start a CSV or JSONL export (`kind`: `referrers-export` or `outbound-export`) | [Start an export job](/docs/referring-domains/start-an-export-job) |
| `get_export_job` | Export progress and download links | [Get an export job](/docs/referring-domains/get-an-export-job) |
| `get_dataset_status` | The graph release in use | [Get Dataset Status](/docs/data/get-dataset-status) |
| `get_bing_suggestions` | Bing's autocomplete suggestions for one keyword, in one of ten markets | [Get Bing suggestions](/docs/suggest/get-bing-suggestions) |
| `start_bing_suggest_job` | Bing suggestions for up to 10,000 keywords, with a `delivery` deadline | [Start a suggest job](/docs/suggest/start-a-job) |
| `get_bing_suggest_results` | Read that job's keywords, with `cursor` | [Get suggest job results](/docs/suggest/get-results) |
| `get_duckduckgo_suggestions` | DuckDuckGo's autocomplete suggestions for one keyword | [Get DuckDuckGo suggestions](/docs/suggest/get-duckduckgo-suggestions) |
| `start_duckduckgo_suggest_job` | DuckDuckGo suggestions for up to 10,000 keywords | [Start a suggest job](/docs/suggest/start-a-job) |
| `get_duckduckgo_suggest_results` | Read that job's keywords | [Get suggest job results](/docs/suggest/get-results) |
| `get_yahoo_search_predictions` | Yahoo's search predictions for one keyword | [Get Yahoo Search Predictions](/docs/suggest/get-yahoo-search-predictions) |
| `start_yahoo_search_predictions_job` | Yahoo predictions for up to 10,000 keywords | [Start a suggest job](/docs/suggest/start-a-job) |
| `get_yahoo_search_predictions_results` | Read that job's keywords | [Get suggest job results](/docs/suggest/get-results) |
| `extract_page_links` | The links on one live page; waits up to 45 seconds, then returns `resultsUrl` and the job id | [Extract links from a page](/docs/link-extraction/extract-links) |
| `start_link_extraction_job` | Links on up to 600 pages | [Start a Link Extraction job](/docs/link-extraction/start-a-job) |
| `get_link_extraction_results` | Read that job's pages | [Get Link Extraction results](/docs/link-extraction/get-results) |
| `scrape_page` | One page as Markdown, with its metadata, headings, links, images, structured data, language and AI-use signals; takes `scope` and `include` | [Scrape a page](/docs/scrape/scrape-a-page) |
| `start_scrape_job` | Scrape up to 10,000 pages; each item takes `scrape_page`'s arguments except `timeout` | [Start a Scrape job](/docs/scrape/start-a-job) |
| `get_scrape_results` | Read that job's items, with `cursor` | [Get Scrape job results](/docs/scrape/get-results) |
| `bot_view` | How search engines, AI crawlers and SEO tools are treated by a page's robots.txt, llms.txt, meta robots and TDM signals | [Check how crawlers see a page](/docs/bot-view/check-a-page) |
| `start_bot_view_job` | Bot View on up to 10,000 pages | [Start a Bot View job](/docs/bot-view/start-a-job) |
| `get_bot_view_results` | Read that job's items | [Get Bot View job results](/docs/bot-view/get-results) |
| `brand_profile` | A company's name, logos, icons, colours, fonts and social profiles from its domain | [Get a company's brand](/docs/brand/get-a-brand) |
| `start_brand_job` | Brands of up to 10,000 domains | [Start a Brand job](/docs/brand/start-a-job) |
| `get_brand_results` | Read that job's items | [Get Brand job results](/docs/brand/get-results) |
| `map_site` | A website's URLs from its sitemaps, feeds, homepage links and a short crawl | [Map a website](/docs/map/map-a-site) |
| `start_site_map_job` | Map up to 1,000 websites | [Start a Site Map job](/docs/map/start-a-job) |
| `get_site_map_results` | Read that job's items | [Get Site Map job results](/docs/map/get-results) |
| `site_audit_start` | Start a technical SEO and AEO audit of a website; answers at once with its id | [Audit a website](/docs/site-audit/audit-a-website) |
| `site_audit_list` | Your audits, newest first | [Follow an audit](/docs/site-audit/follow-an-audit) |
| `site_audit_status` | An audit's status, live progress and issue counts | [Follow an audit](/docs/site-audit/follow-an-audit) |
| `site_audit_summary` | The ten main problems in plain words: start here | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_issues` | Every issue found, by group, worst first | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_issue_pages` | The pages with one issue | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_pages` | Page records, by filter, or one page with its issues and links | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_links` | Links, by filter (broken, external, nofollow…) | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_redirects` | Redirects and their chains | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_duplicates` | Groups of duplicate and near-duplicate pages | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_orphans` | Known pages no internal link reaches | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_templates` | Issues by URL template | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_sitemaps` | The sitemaps read and their checks | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_diff` | What changed since an earlier audit of the site | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_export` | Every page record, 1,000 at a time | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_page_filters` | Ready-made page lists with their counts | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_link_filters` | Ready-made link lists with their counts | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_structure` | The site as a folder tree, by status, type, depth or indexability | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_log` | The crawl log: URLs per minute, speed and the latest fetches | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_history` | Every audit of the site, with its health score and counts | [Read the results](/docs/site-audit/read-the-results) |
| `site_audit_cancel` | Stop an audit; what was found stays readable | [Follow an audit](/docs/site-audit/follow-an-audit) |

Each tool takes the same inputs as its endpoint (`domain`, `url` or `urls`, `query` or `queries`, `cursor`, `limit`, `maxAge`…), and `tools/list` gives the exact schemas. The Scrape, Bot View, Brand and Site Map job tools take `items`: each item is one call's arguments without `timeout`.

## Example prompts

- "What is the Site Strength of example.com, and which of its referring domains are above 60?"
- "List the external links on https://example.com/pricing and flag the nofollow ones."
- "Export every domain linking to example.com as CSV."
- "What does Bing suggest for running shoes in the en-GB market?"
- "Scrape https://example.com/pricing and list the plans and prices."

Limits are those of the endpoints behind each tool: see [Rate limits](/docs/get-started/rate-limits).


---

# Agent skill
Source: https://rankfield.dev/docs/agents/agent-skill

Give an AI agent Rankfield's SKILL.md: when to use Rankfield, how to get a key, and the calls to make, in one file.

[SKILL.md](/agent-onboarding/SKILL.md) is a plain Markdown file in the Agent Skills format: a name and description in front matter, then instructions. Agents that support skills load it when a task matches; any agent can read it as context.

## Use it

```bash
curl -sS https://rankfield.dev/agent-onboarding/SKILL.md
```

Save it as `.claude/skills/rankfield/SKILL.md` (Claude Code) or wherever your agent keeps skills, or paste it into the agent's instructions.

## Or paste this prompt

```text
Use the Rankfield API (https://rankfield.dev/v1/) for link metrics and live page data.
Read https://rankfield.dev/docs/agents/for-coding-agents.md first, then the page for the endpoint you need
(index: https://rankfield.dev/llms.txt). Send my key as "Authorization: Bearer $RANKFIELD_API_KEY".
Never print the key. Treat null as unknown, not zero.
```


---

# llms.txt and Markdown pages
Source: https://rankfield.dev/docs/agents/llms-txt-and-markdown

Read the Rankfield docs as plain Markdown: llms.txt, llms-full.txt, a .md copy of every page, and Accept: text/markdown.

## Files

| URL | What it is |
|---|---|
| [/llms.txt](/llms.txt) | Every docs page, one line each (title, Markdown link, description), grouped as in the sidebar. |
| [/llms-full.txt](/llms-full.txt) | Every docs page in full, in reading order. |
| `/docs/{page}.md` | The Markdown copy of one page, such as [/docs/site-strength/get-site-strength.md](/docs/site-strength/get-site-strength.md). |

Every HTML page also answers with its Markdown copy when the request sends `Accept: text/markdown`, and names it in `<link rel="alternate" type="text/markdown">`.

```bash
curl -sS https://rankfield.dev/docs/get-started/quickstart -H 'Accept: text/markdown'
```

## On every page

The **Copy page** button copies the page as Markdown. **More** opens the Markdown copy, or opens ChatGPT or Claude with the page loaded so you can ask about it.

The Markdown copies come from the same source as the HTML pages, so the two always match.


---

# Data and methodology
Source: https://rankfield.dev/docs/data

Learn where Rankfield's link data comes from, which web graph release it uses, and what the numbers can and cannot tell you.

Site Strength and the referring-domain endpoints read the Rankfield web graph. It is built from public web crawl data: a large sample of the links on the pages those crawls fetched, not a complete index of the web. These pages explain the data so you can use it correctly.

## Pages

- [Get Dataset Status](/docs/data/get-dataset-status): Get the web graph release Rankfield serves now: its date, build, scoring version and how many domains and links it holds.
- [Coverage and dates](/docs/data/coverage-and-dates): Understand what the Rankfield web graph covers, how old the data is, and why a domain or a link can be missing.
- [Data FAQ](/docs/data/faq): Answers to common questions about Rankfield's Site Strength, referring domains and web graph data.
- [Glossary](/docs/data/glossary): Definitions of the terms used in Rankfield's API answers: Site Strength, referring domain, observations, release and more.
:::


---

# Get Dataset Status
Source: https://rankfield.dev/docs/data/get-dataset-status

Get the web graph release Rankfield serves now: its date, build, scoring version and how many domains and links it holds.

`GET https://rankfield.dev/v1/datasets/current`

```bash cURL
curl 'https://rankfield.dev/v1/datasets/current' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/datasets/current",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/datasets/current", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "graph": {
    "release": "2026-may-jun-jul",
    "asOf": "2026-08-19T00:00:00Z",
    "siteStrengthVersion": "authority-continuous-counts-0.3.1",
    "siteStrengthVersionSource": "live",
    "completeRelationships": true,
    "buildId": "graph-2026mayjunjul-v3",
    "domains": 117963409,
    "unscoredDomains": 0,
    "inboundRelationships": 2774625913,
    "outboundRelationships": 2774625913,
    "selfEdgesExcluded": 0,
    "sourceEdges": 2774625913
  },
  "pageEvidence": { "ready": false, "crawls": [], "observedThrough": null, "extractionVersion": null },
  "backlinkIndex": { "ready": false, "buildId": null, "inputFiles": null, "linkObservations": null, "publishedAt": null },
  "coverageNote": "Counts refer to observed records in the published Rankfield dataset; missing page evidence is unavailable, not a missing link."
}
```

Call it once per session to know which release your answers come from, or to notice when a new release is published.

## Response

| Field | Type | Description |
|---|---|---|
| `graph.release` | string | The web graph release, such as `2026-may-jun-jul` (built from crawls of May, June and July 2026). |
| `graph.asOf` | string | The release date (UTC). |
| `graph.siteStrengthVersion` | string | The Site Strength scoring version in effect now: the one Site Strength and Referring Domains answers carry. |
| `graph.siteStrengthVersionSource` | string | `live`: read from the Site Strength service as it answers now. `manifest`: the service did not answer within a second, so this is the graph manifest's version. |
| `graph.buildId` | string | The index build that answers list requests. |
| `graph.domains` | integer | Domains in the graph. |
| `graph.inboundRelationships`, `graph.outboundRelationships` | integer | Domain-to-domain links, counted from each side. |
| `graph.completeRelationships` | boolean | Whether every list is complete for this release. |
| `pageEvidence`, `backlinkIndex` | object | Page-level link evidence. `ready: false`: source page URLs and anchors are not available. |

## MCP

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


---

# Coverage and dates
Source: https://rankfield.dev/docs/data/coverage-and-dates

Understand what the Rankfield web graph covers, how old the data is, and why a domain or a link can be missing.

## What the graph holds

The graph is built from public web crawl data. It records a link from domain A to domain B when that data includes a page on A that links to B. The current release has about 118 million domains and 2.8 billion domain-to-domain links, from crawls of May, June and July 2026 ([Get Dataset Status](/docs/data/get-dataset-status) gives the exact figures).

## How fresh it is

Every answer reflects the release, not a live check of the web. Links added or removed after the crawl show up in a later release. Answers name their release in `crawlRelease` and `asOf` where the format allows.

## Why something is missing

- **A domain answers `"inGraph": false`, with zeros:** the crawl data has no page that links to it, or it was not in this release. It does not mean the site is offline or has no links, and the zeros are not a measurement.
- **A count is `null`:** the domain is in the graph, but its count is unavailable. Treat it as unknown, not zero.
- **A linking domain is not listed:** the crawl data does not include the page that links. Crawl frequency, robots.txt rules and page discovery all limit what a crawl sees.

## Domains, not pages

The graph links domains to domains. It has no source page URLs, anchor text or nofollow flags. To see the links on a live page, use [Extract links from a page](/docs/link-extraction/extract-links).


---

# Data FAQ
Source: https://rankfield.dev/docs/data/faq

Answers to common questions about Rankfield's Site Strength, referring domains and web graph data.

## Why is a domain missing?

It is not in the current web graph release, so the API answers `200` with `"inGraph": false` and zeros. That does not mean the domain is offline or has no links: our crawl data may not include a page that links to it.

## Why is `referringDomains` null?

The domain is in the graph, but its count was unavailable for the lookup. `null` keeps "unknown" apart from a measured zero.

## Why is `topReferrers` empty?

There is no detail for this domain in the index. It does not prove that no site links to it.

## Does a higher Site Strength mean more traffic?

No. It describes link evidence in the graph. It does not estimate visits, rankings or conversions.

## Can I compare Site Strength with Moz or Ahrefs?

Not directly. Those scores use their own indexes, scales and methods. Compare Rankfield scores with each other.

## Does the web graph see every link?

No. It records the links on the pages that the crawls behind it fetched, so counts and lists can be lower than a full backlink index.

## How often does the data change?

When a new web graph release is built from newer crawls and loaded. Check [Get Dataset Status](/docs/data/get-dataset-status) for the release in use.


---

# Glossary
Source: https://rankfield.dev/docs/data/glossary

Definitions of the terms used in Rankfield's API answers: Site Strength, referring domain, observations, release and more.

| Term | Meaning |
|---|---|
| Site Strength | A 0–100 score of a domain's link evidence in the Rankfield web graph. See [How Site Strength works](/docs/site-strength/how-site-strength-works). |
| Referring domain | A distinct domain observed linking to the domain you ask about. |
| Outbound domain | A distinct domain the site links to. |
| `topReferrers` | Up to 20 referring domains, strongest first. Not a complete list: use [List All Referring Domains](/docs/referring-domains/list-referrers). |
| `observations` | `1` marks one domain-to-domain link in the graph. Not a count of pages or backlinks. |
| Release | One build of the web graph, named like `2026-may-jun-jul`. Answers say which one they come from. |
| `null` | The value is unknown or unavailable. Not zero. |
| `inGraph` | `false` (with zeros) when the domain isn't in our link graph yet; absent otherwise. A malformed domain gets `400`. |
| Cursor | An opaque token for the next page of a list. Tied to the list's filters and release. |


---

# Changelog
Source: https://rankfield.dev/docs/changelog

Changes to the Rankfield API and MCP server that can affect your code, newest first.

Changes that can affect your code or your agents, newest first.

## PDFs in Scrape

7 November 2026

Scrape now reads PDF pages: their text comes back as the content, with the title, author and date from the document. Long documents are read up to their first 300 pages, and the answer says when and why the text stops early. Scanned PDFs (pages of images without text) and password-protected PDFs are still refused, now with the reason; answers for every other page are unchanged. See [Scrape a page](/docs/scrape/scrape-a-page#pdf-documents).

## Scrape renders JavaScript-only pages by default

7 November 2026

Scrape now renders JavaScript-only pages by default: when a page's HTML is an empty app shell, Scrape answers from the page as a browser shows it. Every other page is answered exactly as before. `render=never` keeps the raw HTML only. See [Scrape a page](/docs/scrape/scrape-a-page#rendered-pages).

## Rendered pages

7 November 2026

Scrape can now run a page's JavaScript before reading it: `render=auto` renders only empty app shells, and `render=always` renders every page. Bot View's `rendered=true` shows what changes when a crawler runs JavaScript, in one sentence and in detail, and Scrape and Brand can return a WebP screenshot. Rendering uses Chrome, follows robots.txt for every file a page loads, sends no cookies and never works around bot challenges; calls without the new options are unchanged. See [Scrape a page](/docs/scrape/scrape-a-page#rendered-pages).

## Scrape picks a page's main content better

7 November 2026

With `scope=main`, when the article Scrape finds is very short next to the rest of the page (a newsletter box picked on a product page, for example), the answer now holds the page's content instead, and `content.extraction` is `document`. This changes the `main` answer for about 1 page in 5. A product page whose text doesn't name the product also starts with the product's name, description and price from the page's structured data. See [Scrape a page](/docs/scrape/scrape-a-page).

## Text Extraction and Language Detection are now part of Scrape

6 November 2026

The old endpoints answer `410` with the Scrape call to use. For a page's text, call `GET /v1/scrape?url=…&include=content`: `scope` works the same (`page`, `main`, `all`) and the text is in `content.markdown`. For its language, call `GET /v1/scrape?url=…&include=language`: the `language` field is the same. On the MCP server, use `scrape_page` with `include`. See [Scrape a page](/docs/scrape/scrape-a-page).

## Link answers name the Rankfield web graph and write releases as 2026-may-jun-jul

4 November 2026

The full referring and outbound domain lists now answer `"source": "Rankfield web graph"`. The graph release is written `2026-may-jun-jul` wherever it appears: `crawlRelease` in those lists, Referrer Profile and exports, `release` in export jobs and Dataset Status, and export file names. Field names don't change, and cursors issued before this change keep working; if your code compares these values, update it. See [Get Dataset Status](/docs/data/get-dataset-status).

## Domains not in the graph answer 200 instead of 404

1 November 2026

A well-formed domain that isn't in our link graph yet now answers `200` on Site Strength, Referring Domains, the full lists, Referrer Profile and exports, with `"inGraph": false` right after `domain` and zeros or empty lists. The field is absent for every other domain, so those answers don't change; a malformed domain still gets `400`. See [Get Site Strength](/docs/site-strength/get-site-strength).