Importing backlinks from CSV without losing context

Importing backlinks from CSV starts with checking what each column means. Preserve the source page, destination, supplier identity and dates. Then review accepted rows, duplicates and rejections before treating the file as a useful candidate set. An imported row is still a supplier observation until you verify it.

AgentLinkOps has presets for Ahrefs, Search Console, Semrush, Majestic, Moz, DataForSEO, Linkody and generic CSV. The local commands below describe the private CLI reviewed on September 12, 2026. They assume authorized CLI access; public package distribution remains pending.

Keep the original export unchanged

Save the original file before opening it in a spreadsheet or renaming columns. Record which account, report, filters and export date produced it. If the supplier exported only one page of results, keep that detail beside the file.

A candidate set inherits those limits. A file with 500 rows might contain every result from a small report, or one filtered slice of a much larger report. The file alone cannot establish complete backlink coverage.

CSV also has formatting rules. Quoted fields can contain commas, quotes or line breaks, so splitting each line on commas can corrupt a valid record. Use a CSV parser that handles those cases. RFC 4180 documents the common format and quoting conventions.

Identify the source and destination columns

The source is the referring page that may carry a backlink. The target is the destination that backlink points toward. A supplier's report may call these fields “Referring page URL” and “Target URL,” while another export uses different names.

This synthetic file shows the relationship:

source,target,anchor
https://publisher.example/resources,https://example.com/trail-access,trail access guide
https://another.example/reading,https://example.com/trail-access,outdoor access reference

These reserved example domains do not represent verified placements. They only show the shape of an input file. If your export has custom headings, map them explicitly instead of changing the meaning of a supplier preset.

For the illustrated headings, an authorized CLI can preview the file with:

linktrail import backlinks.csv --target example.com --from csv --map source=source,target=target

The current CLI import command reports its mapping and counts. It is preview-only and does not write candidates or add ledger expectations. Hosted import_backlinks is a separate stored-data operation with its own access requirements.

Review all the counts before continuing

Read the accepted, rejected and duplicate counts together. A large input file is not a successful import if nearly every record failed. Repeated rejections often point to a mapping problem rather than thousands of unrelated bad links.

The importer distinguishes rows that the CSV reader could not parse from rows that violate the candidate contract. A malformed row, an invalid source URL and an out-of-scope destination require different corrections. Its rejection report points back to file row positions so you can inspect the original evidence.

Keep duplicate information too. A repeated source-target relationship may come from overlapping export batches or repeated supplier rows. Removing duplicates without preserving their provenance can make a later reconciliation harder. The preview provides enough context to inspect the issue before deciding what to retain.

Preserve supplier dates as supplier dates

An export date describes the file. A supplier's first-seen or last-seen field describes its reported observation. A verifier timestamp describes a separate visit to the source page. Those dates answer different questions.

The CLI accepts --generated-at for a known supplier-generated timestamp. Supply it only when you have that fact. Do not replace an absent supplier date with the import time and present it as evidence that the link was recently seen.

Retain the supplier's link attributes and metrics as reported data. A score from one provider is not interchangeable with a different provider's score. A missing follow/nofollow value should remain unestablished instead of turning into an assumed followed link.

Choose candidates before expecting placements

After a sound preview, decide which candidates deserve research or a fresh check. A competitor export can reveal relevant referring pages, but those pages may have no relationship with your own target. Do not enroll every row as an expected backlink.

Use a repository backlink ledger to record the relationships you want or expect, and keep evidence in its own records. The MCP workflow guide explains the move from stored candidates to a selected check.

Before a hosted import, confirm the project and the required API permissions. After a check, read its actual result and uncertainty. If remote events update your local records, preserve independent sync cursors for their feeds. The agent workflow hub joins import, research and monitoring without collapsing them into one status.

Sources

1. Common Format and MIME Type for Comma-Separated Values (CSV) Files · RFC Editor · 2005-10