Top Pages

Returns the pages on a domain (including its subdomains) ranked by number of inbound links, with the number of distinct linking domains and the page's HTTP status and content type where known. Use it to find the content that earns links. Data comes from the pre-processed link graph snapshot (see Response format).

Request

Parameters

Example

curl "https://api.rankparse.com/v1/top-pages?domain=stripe.com&limit=25" \
  -H "X-API-Key: rp_your_key"

import requests

res = requests.get(
    "https://api.rankparse.com/v1/top-pages",
    params={"domain": "stripe.com", "limit": 25},
    headers={"X-API-Key": "rp_your_key"},
    timeout=90,
)
res.raise_for_status()
body = res.json()
if body.get("partial"):
    print("Partial result: treat as a preview")
for page in body["data"]:
    print(page["inbound_links"], page["referring_domains"], page["url"])

const params = new URLSearchParams({ domain: "stripe.com", limit: "25" });

const res = await fetch(`https://api.rankparse.com/v1/top-pages?${params}`, {
  headers: { "X-API-Key": "rp_your_key" },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const body = await res.json();
console.log(body.data, body.partial ?? false);

Response

{
  "domain": "stripe.com",
  "data": [
    {
      "url": "https://stripe.com/",
      "inbound_links": 5678,
      "referring_domains": 1234,
      "status_code": 200,
      "mime": "text/html"
    },
    {
      "url": "https://stripe.com/docs",
      "inbound_links": 2210,
      "referring_domains": 640,
      "status_code": 200,
      "mime": "text/html"
    }
  ],
  "total": 2,
  "limit": 25,
  "credits_used": 2,
  "credits_remaining": 996
}

Response fields

Top level:

Each row in data:

Behavior and limits

Large domains and partial results

For domains with very large link graphs the query can exceed its time budget and fail with 503 and code: "query_timeout". One retry may succeed. If the same domain keeps timing out, try a narrower subdomain, because the endpoint may not currently support the full domain. Failed requests are refunded.

If the aggregating query fails but a simpler fallback completes, the response includes partial: true. That result is incomplete because duplicate page URLs are not merged, so treat it as a preview rather than a full ranking. Partial responses are billed normally but are not cached.

Other behavior

• Credits: 2 per call, charged before the lookup. Server errors are refunded.
• Caching: complete results are cached for 30 days per crawl release and per combination of domain and limit. A cache hit is billed the same as a fresh lookup.
• Empty results: a domain with no data returns 200 with data: [], never 404.
• Rate limit: 60 requests per minute per key. See Rate limiting.

Errors

See Errors for the full list and the error body format.

Related

MCP tool: get_top_pages (accepts domain, limit).