# Broken Links

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

Canonical: https://docs.georanker.com/docs/seo-tools-api-broken-links

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.

```bash
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.

```json
{
  "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](https://docs.georanker.com/docs/broken-links)

## 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.

```bash
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](https://seoapi.georanker.com/api/docs#/Broken%20Links)

[SEO Tools API overview](https://docs.georanker.com/docs/seo-tools-api)
