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.
Find the link to fix
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