Redirect Mapping From a CSV for a Site Migration

A redirect map is a CSV with two columns, old path and new path, one row for every URL on the old site that changes. Each row becomes a permanent (301) redirect on the new site. If the map is complete and every row points at the page that replaces the old one, rankings mostly carry over. If rows are missing or point at the wrong place, they do not. No other document in a migration has that much effect on search traffic.

This post is part of our guide to Migrating a Website With AI.

Where the map comes from

The map is the last two columns of the content inventory: old URL and new URL. If you built the inventory the way Content Inventory With an AI Agent describes, the map is a filter on that spreadsheet: every row where the new URL differs from the old one. Rows marked drop are left out, and rows where the path stays the same need no redirect at all.

That last point is the cheapest win in any migration. If the old site had /services/web-design and the new site can have /services/web-design, keep it. Google's documentation on site moves with URL changes is built around mapping old URLs to new ones; a URL that does not change needs no mapping and loses nothing. Before you write a single redirect, ask how many old paths the new site can simply reproduce.

The rules Google publishes

Google's redirects documentation and its site move guide are short, and the rules that matter for a map fit in a list.

Use a permanent redirect. HTTP 301 or 308. Google treats a permanent redirect as a signal that the target should become the canonical URL. A temporary redirect (302, 307) does not send that signal, which is the opposite of what a migration wants.
Server-side, not JavaScript. Google recommends a permanent server-side redirect whenever possible and keeps JavaScript redirects as a last resort, because if rendering fails, Google may never see the redirect at all. A hosted builder that writes redirects at the edge gives you server-side behavior without a server.
One hop. Redirect each old URL straight to its final destination. Google's site move guide says Googlebot can follow up to 10 hops but advises keeping chains ideally no more than 3 and fewer than 5. In a map built from scratch there is no reason to have more than one.
No catch-all to the home page. The site move guide says not to redirect many old URLs to one irrelevant destination, such as the home page of the new site, and warns that this may be treated as a soft 404. A page with no replacement should return 404.
Merged content can share a target. If three old posts became one new page, three rows point at that page. That is consolidation, not a catch-all.
Keep the redirects. The site move guide says generally at least a year, ideally longer. People and other sites keep using old links for much longer than that.

Building the file

The format is a CSV with a header row and two columns. Old path, new path. Paths, not full URLs, unless the target is on another domain.

old_path,new_path
/blog/2019/05/our-new-office,/post/our-new-office
/services/web-design/,/services/web-design
/tag/wordpress,/post
/about-us.html,/about

A few conventions that save trouble:

Match the old path exactly as it was served. Trailing slash or no trailing slash, .html or not, upper or lower case. Take the paths from the crawl, not from memory. If the old site served both /about and /about/, add both rows.
Include the query string only when it changed the page. A ?utm_source= parameter did not; a ?p=123 on an old WordPress site did.
Include files. Old PDFs, images that were linked from other sites, feed URLs. Google's site move guide says to include embedded content such as images and videos in the move plan.
Old blog archive, tag and author pages usually have no new equivalent. Decide as a group: redirect to the blog index if they had traffic, or let them 404 if they did not.
Order the rows by old traffic. Review the top 50 by hand. Those rows are the ones that decide your rankings. The rest can be checked by sampling.
Fold in the old site's own redirects. If the old site already redirected /a to /b, and /b now moves to /c, write /a to /c and /b to /c. Otherwise the first link in the chain lives on the old host and disappears with it.

An AI agent is good at the mechanical part: producing the rows from the inventory, normalizing slashes and case, finding every old path that has no row, and flagging rows whose target does not exist on the new site. It is not good at deciding where a page with no obvious equivalent should go. Those rows need you.

Testing the map before launch

Three checks, in order:

Every target exists. A redirect to a 404 is a lost page twice over. The agent can fetch every new path on the draft and list the ones that fail.
No chains. No new path in the map should appear as an old path in another row. If it does, collapse the two rows into one.
No loops. No row where old and new are the same, and no pair that point at each other.

All three can be one instruction to the agent: "For every row in redirects.csv, confirm the new path exists on the draft site, that it does not appear in the old_path column, and that old and new differ. Write the failures to problems.csv with the reason." It is the kind of check an agent does quickly and completely, and a person does slowly and with gaps.

After launch, test the real thing. A short script that requests each old URL and prints where it lands is the fastest proof that the map works on the live domain:

while IFS=, read -r old new; do
  printf '%s -> ' "$old"
  curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' "https://example.com$old"
done < <(tail -n +2 redirects.csv)

Every line should show 301 and the new URL. A 404 is a missing row; a 200 means the old path still exists as a page; a redirect to the wrong place is a typo in the map. Then check a sample with Search Console's URL Inspection tool, which the site move guide recommends for testing individual URLs. What to watch in the weeks after is in The Week After a Migration.

A note on domain changes

If the domain changes along with the paths, the map stays the same shape, but every target is on the new domain, and you also use Search Console's Change of Address tool after the redirects are live. Its effect lasts 180 days, and Google asks you to keep the redirects in place for at least that long, longer if the old URLs still get traffic from search. The tool works only on domain-level properties, so a move between paths on the same domain does not use it.

When the old site is a generated app

The same map works when the old site was generated by an AI app builder rather than run on a CMS. The old URLs come from the app's router instead of a sitemap, so take them from Search Console and a crawl, and the inventory is usually smaller. Two things differ. Routes that only exist in the browser may never have been indexed, so check Search Console before writing rows for them. And if the app served the same page at several paths, pick one target and redirect the rest to it. The redirect step itself is the one in this post.

How this works in Beste

Beste imports bulk 301 redirects from a CSV on Pro. The file has two columns, old path and new path, and the technical SEO page has an example template to download. Before anything is saved, the import shows a preview that sorts every row into one of three groups, and each group tells you something:

Matched. The new path is a page on the site. These are the rows you expect.
Duplicates. The same old path appears twice. Pick one target and delete the other row; two answers for one URL is a bug in the map, not a choice for the platform to make.
Unmatched. The target is not a page on the site. Either it is a typo, a page you have not built yet, or a real destination elsewhere. Rows like the last case can be imported as external redirects, which covers a domain change or content that moved to another site.

Nested pages reproduce most old paths exactly, which is why the map is usually much shorter than the inventory. Single redirects can be added from the editor or by an agent with add_redirect over the MCP server, which is how an agent adds a row when it removes or renames a page later; your rules file is the place to say it must always do that. Redirects are served by the hosting layer, so they are server-side in Google's sense, and the sitemap is regenerated on publish with the new paths.

One plan detail matters more than it looks. Redirects are a Pro feature whether added one at a time or imported, and per the pricing page, if a Pro plan is cancelled the site stays live but redirects stop working. Google asks for a year at least and old links live longer than that. Budget for Pro for as long as the old URLs still bring visitors. If you have not connected an agent yet, the MCP guide covers the setup.