# Broken link checker API

Crawl a site and find broken links, images and scripts, with the pages that link to each.

`POST /v1/broken-links`

- Price: Costs 5 credits per 50 pages (rounded up). The maximum is reserved when the job starts, and you pay only for the pages crawled. Failed runs are free.
- Cache: Answers are cached for up to 15 minutes, per account except for a site's home page; send fresh=true to ask the source again.
- MCP tool: `check_broken_links`

Broken, redirected and unverifiable links found by crawling a site, with the pages that link to them. Costs 5 credits per 50 pages (rounded up). The maximum is reserved when the job starts, and you pay only for the pages crawled. Failed runs are free. Answers are cached for up to 15 minutes, per account except for a site's home page; send fresh=true to ask the source again.

## Request body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | A page URL or a domain; a domain means its home page. |
| `max_pages` | integer | no | Pages to crawl on this site; costs 5 credits per 50. |
| `external` | boolean | no | Also check links to other sites. |
| `fresh` | boolean | no | Skip the cache and ask the source again; costs the same. |

## Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `job_id` | string | yes | The job's ID; poll GET /v1/jobs/{id} |
| `tool` | string | yes |  |
| `target` | string | yes |  |
| `status` | "ok" | "partial" | "error" | yes |  |
| `fetched_at` | string | no |  |
| `cached` | boolean | no |  |
| `credits_used` | integer | no | Credits this call took from your balance. 0 for free tools, for a replay of an earlier call, and for a free check run on the website without signing in |
| `summary` | string | yes |  |
| `score` | integer or null | no |  |
| `findings` | array of object | no |  |
| `credits_remaining` | integer | yes | Your balance after this call. It can be below zero after a refund; free tools still work then |
| `data` | object | yes | This tool's result |
| `data.start_url` | string | yes |  |
| `data.max_pages` | integer | yes |  |
| `data.external` | boolean | yes |  |
| `data.pages_crawled` | integer | yes |  |
| `data.stopped` | "completed" | "page_limit" | "link_limit" | "deadline" | "cancelled" | yes |  |
| `data.duration_s` | number | yes |  |
| `data.pages` | array of object | yes |  |
| `data.broken` | array of object | yes |  |
| `data.broken.url` | string | yes |  |
| `data.broken.kind` | "internal" | "external" | yes |  |
| `data.broken.resource` | "page" | "image" | "script" | "stylesheet" | yes |  |
| `data.broken.status` | integer or null | yes |  |
| `data.broken.reason` | string | yes |  |
| `data.broken.referrers` | array of object | yes |  |
| `data.broken.referrer_count` | integer | yes |  |
| `data.unverified` | array of object | yes |  |
| `data.unverified.url` | string | yes |  |
| `data.unverified.kind` | "internal" | "external" | yes |  |
| `data.unverified.resource` | "page" | "image" | "script" | "stylesheet" | yes |  |
| `data.unverified.status` | integer or null | yes |  |
| `data.unverified.reason` | string | yes |  |
| `data.unverified.referrers` | array of object | yes |  |
| `data.unverified.referrer_count` | integer | yes |  |
| `data.timeouts` | array of object | yes |  |
| `data.timeouts.url` | string | yes |  |
| `data.timeouts.kind` | "internal" | "external" | yes |  |
| `data.timeouts.resource` | "page" | "image" | "script" | "stylesheet" | yes |  |
| `data.timeouts.status` | integer or null | yes |  |
| `data.timeouts.reason` | string | yes |  |
| `data.timeouts.referrers` | array of object | yes |  |
| `data.timeouts.referrer_count` | integer | yes |  |
| `data.redirected_internal` | array of object | yes |  |
| `data.skipped` | object | yes |  |

## Errors

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `402` Balance below the call's price (`insufficient_credits`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)
- `503` Too many open event streams on this server, the checked site is getting too many checks, or the browser or link checker is busy; try again after the seconds in the Retry-After header (`busy`, `site_busy`, `browser_busy`, `crawl_busy`). Not charged

## Example

```sh
curl -X POST "https://api.dnssuper.com/v1/broken-links" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"example.com"}'
```

```python
import os

import httpx

client = httpx.Client(
    base_url="https://api.dnssuper.com",
    headers={"Authorization": f"Bearer {os.environ['DNSSUPER_API_KEY']}"},
    timeout=60,
)
response = client.post("/v1/broken-links", json={
    "url": "example.com",
})
response.raise_for_status()
result = response.json()
print(result["summary"], result["credits_used"])
```

```ts
const response = await fetch("https://api.dnssuper.com/v1/broken-links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"url":"example.com"}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result.summary, result.credits_used);
```

Example response:

```json
{
  "job_id": "7a5dfd02-262a-51e2-a6f7-5edef555df9c",
  "status": "queued",
  "total": 1,
  "credits_reserved": 5,
  "duplicates_removed": 0,
  "job_url": "https://api.dnssuper.localhost/v1/jobs/7a5dfd02-262a-51e2-a6f7-5edef555df9c",
  "items_url": "https://api.dnssuper.localhost/v1/jobs/7a5dfd02-262a-51e2-a6f7-5edef555df9c/items",
  "events_url": "https://api.dnssuper.localhost/v1/jobs/7a5dfd02-262a-51e2-a6f7-5edef555df9c/events"
}
```

## MCP

```json
{
  "tool": "check_broken_links",
  "arguments": {
    "url": "example.com"
  }
}
```

```text
5 broken links found on example.com (14 pages crawled, 28 links checked).
Crawled 14 pages (completed)
Broken: 5 (2 on the site, 1 resource, 2 to other sites); unverified 5; timed out 1
404 https://example.com/missing <- https://example.com/ ("Spring sale")
500 https://example.com/error <- https://example.com/blog/1 ("Comments")
404 https://example.com/img/gone.png <- https://example.com/ ("Banner")
nxdomain https://gone.example.org/ <- https://example.com/blog/2 ("A closed shop")
404 https://www.example.org/gone <- https://example.com/ ("Old partner page")
- fail: Links to your own pages are broken. Fix: Fix or remove the links listed.
- fail: Images, scripts or styles don't load. Fix: Fix the file paths or restore the files.
- warn: Links to other sites are broken. Fix: Update or remove the links listed.
- warn: Some links didn't answer in time. Fix: Check them by hand; the sites may be slow.
+4 more findings (pass detail='full' to see all)
Credits: 5 credits used, 498 remaining | fresh | checked 2026-11-14 10:00 UTC
```
