GeoRanker Docs
SEO Tools APIReport guides

Broken Links

Crawl a URL and find broken links and the pages that use them.

Crawl links from a starting URL and find the page to edit when a destination fails. For example, if a hotel guide links to an old booking page that returns HTTP 404, the report identifies both the guide and the failed destination.

Start a crawl

Set SEO_TOOLS_API_KEY to your API key. This example uses curl and jq, requests a domain crawl, caps it at 25 pages and includes links to external destinations. Replace https://example.com/ with the site to check.

API='https://seoapi.georanker.com'
CRAWL_ID=$(curl --fail-with-body -sS "$API/api/broken-links" \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/",
    "scope": "domain",
    "maxDepth": 2,
    "maxPages": 25,
    "checkExternalLinks": true
  }' | jq -er '.id')

curl --fail-with-body -sS "$API/api/broken-links/$CRAWL_ID" \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY" | jq .

All five fields in the example are required. The public schema lists domain and path for scope and sets a minimum of 1 for maxDepth and maxPages. maxDepth limits how far the crawl follows links from the starting URL. maxPages caps the pages it crawls. The signed-in form uses the scope labels Site and Page. The public schema does not define a mapping between the form choices and the API values. To associate the report with a project, include its UUID as campaignId.

The POST returns HTTP 201 with an id. The GET returns the crawl settings and isComplete. If it is false, wait a few seconds and repeat the GET using the same ID.

The viewer reads individual checks from results.results, a part of the response that the public schema leaves unspecified. This illustrative excerpt shows one failed link.

{
  "url": "https://example.com/",
  "isComplete": true,
  "results": {
    "results": [
      {
        "source_url": "https://example.com/city-guide",
        "checked_url": "https://example.com/old-booking-page",
        "status_code": 404,
        "link_text": "Book a room",
        "is_broken": true
      }
    ]
  }
}

Here the fix belongs on /city-guide. Look for the link text "Book a room" and correct its destination. A check can also contain a link_type or an error when there is no HTTP status code. Filter on is_broken to keep those failures in the results. Read a Broken Links report

Check the repair

Re-run the existing crawl after editing the source page. The redo call returns an ok flag when re-queued. Read the same report ID again for the updated results.

curl --fail-with-body -sS -X POST "$API/api/broken-links/$CRAWL_ID/redo" \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY" | jq .

To list a project's crawls, call GET /api/projects/{projectId}/broken-links and read the reports array. Broken Links API reference

SEO Tools API overview