# Broken Backlink Checker: 404 Link Reclamation + 301 Map (`cygnix_labs/backlink-reclamation-finder`) Actor

Broken backlink checker for GSC, Ahrefs or Semrush exports: finds linked-to pages that now 404, soft-404, 5xx or redirect-chain, matches each to the best live page, and outputs a 301 redirect map (.htaccess, nginx, CSV) ranked by referring domains. $0.03/site.

- **URL**: https://apify.com/cygnix_labs/backlink-reclamation-finder.md
- **Developed by:** [Umair Saleem Mohammad Saleem](https://apify.com/cygnix_labs) (community)
- **Categories:** SEO tools, AI, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$30.00 / 1,000 site analyzeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Broken Backlink Checker: 404 Link Reclamation + 301 Redirect Map

**The cheapest backlinks are the ones you already earned.** After a redesign, migration or content cleanup, other sites keep linking to URLs that now return 404, and that link equity is wasted. This Actor takes your backlink export, checks every linked-to URL on your site live, matches each broken one to the best live replacement page, and gives you a ready **301 redirect map ranked by referring domains**.

Site crawlers and broken link checkers only follow your *internal* links, so they miss pages that nothing on your site links to anymore but other sites still do. This starts from the backlinks instead.

### What it finds

| Issue | Meaning | What you get |
|---|---|---|
| NOT_FOUND_404 / GONE_410 | Linked-to page is gone | 301 to the closest live page |
| REDIRECT_TO_BROKEN | An old redirect now ends in a 404 | 301 straight to a live page |
| SOFT_404 | Returns 200 but shows "not found" (or the site's error page) | 301 + "make your error page return 404" |
| REDIRECT_TO_HOMEPAGE | Deep URL redirected to `/` (Google treats it as a soft 404) | 301 to a relevant page instead |
| REDIRECT_CHAIN | 2+ hops before the final page | One-hop 301 to the final page |
| TEMPORARY_REDIRECT | 302/307 instead of 301 | Make it a 301 |
| SERVER_ERROR | 5xx | Flagged: fix the server, never redirect |

### How replacements are matched

Live candidates come from your XML sitemap (index sitemaps, Yoast, Rank Math and WordPress core sitemaps are followed) plus the links on your homepage. Each broken URL is scored against every candidate on slug words, slug similarity and same section, plus the old page title and anchor text when your export has them. The top candidates are fetched to confirm they are live and to compare titles. Matches get HIGH / MEDIUM / LOW confidence; LOW lines are written commented out as `# REVIEW`. **It never suggests the homepage.**

### Input

- **Your site**, e.g. `https://example.com`.
- **A backlink export**, pasted or as a public CSV link (up to 5, combined):
  - Google Search Console: Links > Top linked pages (External) > Export. Free.
  - Ahrefs: Best by links or Backlinks export (UTF-16 tab files work as is).
  - Semrush: Indexed pages or Backlinks export. Moz and Majestic exports also work.
  - No export? List the linked-to URLs instead.
- Optional: sitemap URL, max URLs (default 100, max 500), min referring domains, delay.

### Output

- **Dataset**: one row per linked-to URL, broken ones first: `url`, `referringDomains`, `issue`, `httpStatus`, `hops`, `redirectTo`, `confidence`, `matchWhy`, `alternatives`, `topLinkingPages`, `anchors`.
- **Key-value store**: `REPORT` (client-ready Markdown), `REDIRECTS_HTACCESS` (Apache/LiteSpeed, including query-string URLs), `REDIRECTS_NGINX`, `REDIRECT_MAP_CSV` (imports into the WordPress Redirection plugin, Rank Math or Yoast), `SUMMARY`.

### Pricing

**$0.03 per site analyzed** (pay per event), for up to 500 linked-to URLs in one run. Empty input, an invalid site, an export with no URLs on your site, or an unreachable site are not charged.

### Polite and safe

Identifies itself as `CygnixBacklinkReclaim`, obeys robots.txt (URLs it may not fetch are reported as skipped), waits between requests (default 1 s). Only checks the site you enter. No logins, no paid APIs, no access to your Search Console or SEO tool accounts.

### FAQ

**Do I need Ahrefs or Semrush?** No. The free Search Console "Top linked pages" export is enough.

**How is this different from a broken link checker?** Broken link checkers crawl your internal links. This checks the URLs that *other sites* link to, ranked by referring domains, and writes the redirects.

**Does it verify my backlinks still exist?** No. Referring-domain counts come from your export. It checks your site's target URLs and finds replacements.

**Can I run it for client sites?** Yes, one site per run; agencies can schedule it monthly after each backlink export.

Also available as an AI agent skill on Agensi (Backlink Reclamation Finder). Agency white-label audits: https://skills.cygnixlabs.com/pricing. Support: info@cygnixlabs.com. Made by Cygnix Labs.

# Actor input Schema

## `site` (type: `string`):

The site the backlinks point to (yours, or a client's with permission), e.g. https://example.com. www and non-www are treated as the same site.

## `backlinksCsv` (type: `string`):

Paste a backlink export: Google Search Console Links > Top linked pages > Export (free), Ahrefs Best by links / Backlinks, Semrush Indexed pages / Backlinks, Moz or Majestic. Any CSV/TSV with a target URL column works; referring domains are used for ranking.

## `backlinksCsvUrls` (type: `array`):

Public links to CSV exports (e.g. a Google Sheet published as CSV, Dropbox/Drive direct link). Up to 5, combined with the pasted CSV.

## `targetUrls` (type: `array`):

No export? List the URLs on your site that other sites link to. Without referring-domain counts they are checked in the order given.

## `sitemapUrl` (type: `string`):

Where to find live replacement pages. Default: Sitemap lines in robots.txt, then /sitemap.xml, /sitemap_index.xml, /wp-sitemap.xml. Homepage links are always added.

## `maxUrls` (type: `integer`):

Highest referring domains first. Max 500 per run.

## `minReferringDomains` (type: `integer`):

Skip URLs with fewer referring domains than this.

## `delaySecs` (type: `number`):

Polite checking; robots.txt is always respected.

## Actor input object example

```json
{
  "site": "https://plausible.io",
  "backlinksCsv": "Target URL,Referring domains\nhttps://plausible.io/blog/google-analytics-cookies,40\nhttps://plausible.io/blog/google-analytics-cookie-consent-old,12\nhttps://plausible.io/blog/open-source-website-analytics-2019,8",
  "maxUrls": 100,
  "minReferringDomains": 0,
  "delaySecs": 1
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `report` (type: `string`):

No description

## `htaccess` (type: `string`):

No description

## `nginx` (type: `string`):

No description

## `csv` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "site": "https://plausible.io",
    "backlinksCsv": `Target URL,Referring domains
https://plausible.io/blog/google-analytics-cookies,40
https://plausible.io/blog/google-analytics-cookie-consent-old,12
https://plausible.io/blog/open-source-website-analytics-2019,8`
};

// Run the Actor and wait for it to finish
const run = await client.actor("cygnix_labs/backlink-reclamation-finder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "site": "https://plausible.io",
    "backlinksCsv": """Target URL,Referring domains
https://plausible.io/blog/google-analytics-cookies,40
https://plausible.io/blog/google-analytics-cookie-consent-old,12
https://plausible.io/blog/open-source-website-analytics-2019,8""",
}

# Run the Actor and wait for it to finish
run = client.actor("cygnix_labs/backlink-reclamation-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "site": "https://plausible.io",
  "backlinksCsv": "Target URL,Referring domains\\nhttps://plausible.io/blog/google-analytics-cookies,40\\nhttps://plausible.io/blog/google-analytics-cookie-consent-old,12\\nhttps://plausible.io/blog/open-source-website-analytics-2019,8"
}' |
apify call cygnix_labs/backlink-reclamation-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,cygnix_labs/backlink-reclamation-finder"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/u9XLabQLgyQTu0cxc/builds/K2YCDuJf0J16SulNm/openapi.json