Internal Link Opportunity Finder

Find source-backed internal linking opportunities by matching explicit target keywords and target URLs against visible source-page text. The Actor checks headings, sentence context, and existing anchors before emitting a recommendation. Each row tells an editor where the keyword appeared, whether the exact target link already exists, and why the opportunity was selected.

Use it for content-hub planning, internal-link implementation sheets, refresh workflows, and link coverage reviews. The Actor does not invent semantic relationships: a configured keyword must be visible on an accepted source page, and every target requires an explicit URL.

How matching works

Provide targetKeywords and targetUrls in matching order. A keyword may also be an object containing keyword and targetUrl. For each accepted source page, the Actor:

1. extracts visible text, headings, and anchor destinations;
2. resolves target URLs against the source URL;
3. checks whether an exact target link is already present;
4. counts visible keyword occurrences;
5. captures bounded sentence context and a section hint;
6. returns an opportunity only when the source evidence supports it.

excludeExistingLinks removes targets that already have an exact link. Disable it when reviewing existing anchors and placement quality. anchorSuggestionMode can preserve the exact configured phrase or use a matching heading when one is present. Suggestions remain editorial inputs, not automatic link changes.

Input

Field	Purpose	Default / cap
sourceUrls	Pages on which links may be added or reviewed	empty
targetUrls	Destination URLs paired with keywords	empty
targetKeywords	Visible phrases or { keyword, targetUrl } records	empty
maxSourcePages	Maximum source pages analyzed	10 default, 25 maximum
maxOpportunities	Maximum emitted opportunity rows	50 default, 250 maximum
excludeExistingLinks	Remove exact target links already present	true
anchorSuggestionMode	exact, standard, or contextual	standard
htmlInputs	Captured source records with sourceUrl and HTML	empty
allowedDomains	Optional hostname allowlist for source retrieval	empty
maxPages	Maximum pages retrieved	1 default, 25 maximum
includeEvidence	Preserve evidence excerpts in rows	true
includeRawSnapshots	Store accepted raw source HTML	false
maxChargeUsd	Stop before the next event exceeds this amount	35 USD maximum

Example:

{
  "sourceUrls": [
    "https://publisher.example/guides/reliable-workers"
  ],
  "targetUrls": [
    "https://publisher.example/guides/queue-retries",
    "https://publisher.example/guides/monitoring"
  ],
  "targetKeywords": [
    "queue retries",
    "operational monitoring"
  ],
  "excludeExistingLinks": true,
  "anchorSuggestionMode": "standard",
  "maxOpportunities": 25,
  "allowedDomains": ["publisher.example"],
  "maxChargeUsd": 5
}

The Store default has no sources or target mappings and returns a nonempty source_required diagnostic. Missing keyword-to-URL mappings return targets_required, and pages with no supported match return a clear no-opportunity diagnostic.

Dataset output

Every row preserves provenance and the opportunity decision:

• sourceUrl and pageTitle identify the source page;
• targetUrl and targetKeyword identify the configured destination pair;
• suggestedAnchor preserves the exact phrase or matching heading;
• sourceContext quotes bounded visible context around the keyword;
• existingLinkFound records exact target-link presence;
• opportunityScore combines occurrence, heading, missing-link, and context signals;
• reasonCode explains the decision path;
• linkPlacementHint identifies a matching section or quoted context;
• issueCode, evidenceSnippet, and recommendation support review.

The score ranks supported matches; it does not prove that adding a link improves rankings or reader experience. Editors should validate intent, destination quality, anchor naturalness, and navigation value.

Reports

When includeReport is enabled, key-value storage receives a Markdown summary, CSV records, issue JSON, bounded evidence excerpts, and run metadata. Raw accepted source HTML is stored only when explicitly requested.

Pay-per-event pricing

Event	Price (USD)	When charged
actor-start	0.0350	after successful startup
url-analyzed	0.0115	once for each accepted source URL
link-signal-extracted	0.0115	before a supported link signal is recorded
internal-link-opportunity-generated	0.0115	before each paid opportunity row
executive-report-generated	0.4000	before report artifacts are stored

Apify platform usage pass-through is off. Higher-tier Store discounts are reserved in the pricing policy. The run checks maxChargeUsd before each event; rejected, partial, or over-budget charges stop the related output write.

Safety and interpretation

Only HTTP and HTTPS source pages are retrieved. Loopback and private IPv4 targets are rejected, optional allowlists restrict accepted source hosts, and page counts, opportunity counts, response size, and timeouts remain bounded. Discovered links are inspected but not crawled. Access-denied and human-verification pages become diagnostics.

The Actor reads visible source content and exact anchors only. It does not edit pages, follow authenticated links, determine search-engine policy compliance, or promise ranking effects. Review every recommendation in the context of the source article and destination page before implementation.