# Referring Domains API

> Returns how many distinct domains link to a domain in the Rankfield web graph, and the 20 strongest of them with their Site Strength.

Need every linking domain, not the top 20? Use [All Referring Domains](https://rankfield.dev/endpoints/referrers).

- Page: https://rankfield.dev/endpoints/referring-domains
- Full reference: https://rankfield.dev/docs/referring-domains/get-referring-domains

## Request

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

Send `Authorization: Bearer YOUR_API_KEY`. Get a free key at https://rankfield.dev/?tab=key#playground (no account).

```bash
curl "https://rankfield.dev/v1/domains/github.com/referring-domains" \
  -H "Authorization: Bearer $RANKFIELD_API_KEY"
```

Response:

```json
{
  "domain": "github.com",
  "referringDomains": 748920,
  "topReferrers": [
    { "domain": "googleapis.com", "siteStrength": 100, "observations": 1 },
    { "domain": "google.com", "siteStrength": 100, "observations": 1 },
    { "domain": "youtube.com", "siteStrength": 100, "observations": 1 }
  ]
}
```

## Parameters

| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
| `domain` | path | string | yes |  | A domain such as `github.com`. Case and a leading `www.` are ignored; a URL works too, URL-encoded. |

## Response

| Field | Type | Description |
|---|---|---|
| `domain` | string | The domain as we read it. |
| `inGraph` | boolean | Only when the domain isn't in our link graph yet: `false`, with zeros. Absent otherwise. |
| `referringDomains` | integer \| null | Distinct domains that link to it. `null` when the count is unavailable. |
| `topReferrers` | array | Up to 20 linking domains, strongest first: `domain`, `siteStrength` (0 to 100, or `null` when unscored) and `observations`. |
| `topReferrers[].observations` | integer | Always `1` today: one domain-to-domain connection. It is not a count of pages or backlinks. |

## Errors

Errors come as `{"error":{"message":"…"}}` with the HTTP status.

| Status | When |
|---|---|
| 400 | The domain is not valid: `{"error":{"message":"Invalid domain"}}`. |
| 401 | The key is missing, unknown or revoked. |
| 429 | Only while the graph service is down and its fallback is busy. Wait for `Retry-After`. |
| 503 | The graph is briefly unavailable. Retry after `Retry-After`. |

## Price and limits

- Free; no per-call charge.
- No daily quota or concurrency cap per key.

## Notes

- Data: the Rankfield web graph, built from public web crawl data of May–July 2026 (`2026-may-jun-jul`), 117,963,409 domains. [Dataset Status](https://rankfield.dev/endpoints/dataset-status) tells you which release answered. A domain that isn't in our link graph yet answers `200` with `"inGraph": false` and zeros; the field is absent otherwise, and a malformed domain gets `400`.

## MCP

Tools on https://rankfield.dev/mcp: `get_referring_domains`.