Docs menu

Broken link checker

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

Run it in the browser

Request body

Request body fields
NameTypeDescription
url (required)stringA page URL or a domain; a domain means its home page.
max_pagesintegerPages to crawl on this site; costs 5 credits per 50.
externalbooleanAlso check links to other sites.
freshbooleanSkip the cache and ask the source again; costs the same.

Response

Response fields
NameTypeDescription
job_id (required)stringThe job's ID; poll GET /v1/jobs/{id}
tool (required)string
target (required)string
status (required)"ok" | "partial" | "error"
fetched_atstring
cachedboolean
credits_usedintegerCredits 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 (required)string
scoreinteger or null
findingsarray of object
credits_remaining (required)integerYour balance after this call. It can be below zero after a refund; free tools still work then
data (required)objectThis tool's result
data.start_url (required)string
data.max_pages (required)integer
data.external (required)boolean
data.pages_crawled (required)integer
data.stopped (required)"completed" | "page_limit" | "link_limit" | "deadline" | "cancelled"
data.duration_s (required)number
data.pages (required)array of object
data.broken (required)array of object
data.broken.url (required)string
data.broken.kind (required)"internal" | "external"
data.broken.resource (required)"page" | "image" | "script" | "stylesheet"
data.broken.status (required)integer or null
data.broken.reason (required)string
data.broken.referrers (required)array of object
data.broken.referrer_count (required)integer
data.unverified (required)array of object
data.unverified.url (required)string
data.unverified.kind (required)"internal" | "external"
data.unverified.resource (required)"page" | "image" | "script" | "stylesheet"
data.unverified.status (required)integer or null
data.unverified.reason (required)string
data.unverified.referrers (required)array of object
data.unverified.referrer_count (required)integer
data.timeouts (required)array of object
data.timeouts.url (required)string
data.timeouts.kind (required)"internal" | "external"
data.timeouts.resource (required)"page" | "image" | "script" | "stylesheet"
data.timeouts.status (required)integer or null
data.timeouts.reason (required)string
data.timeouts.referrers (required)array of object
data.timeouts.referrer_count (required)integer
data.redirected_internal (required)array of object
data.skipped (required)object

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

curl

curl
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

Python (httpx)
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"])

TypeScript

TypeScript (fetch)
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
Example response
{
  "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

MCP tool call
{
  "tool": "check_broken_links",
  "arguments": {
    "url": "example.com"
  }
}
Compact MCP output
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