> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Model migrations

> Prove a candidate model on your eval suite, mirror a share of real traffic to it, then cut over by updating the routing policies you choose.

A migration moves production traffic from your current model to a candidate in three phases you advance yourself: pass your evals, shadow real traffic, then cut over, so you prove the model before customers see it.

## Set up

On a suite's **Migration** tab in [Evals](https://gateway.merge.dev/evals), pick the current and candidate models, set **Shadow sampling** (25%, 50%, 75%, or 100% of matching traffic), and optionally a **Daily shadow budget** in USD. Mirroring pauses at the budget and resumes the next UTC day.

The migration starts as a draft and mirrors nothing until you start shadowing. A baseline model can have one draft, shadowing, or paused migration at a time, and an unreverted completed migration blocks new ones for that baseline.

## Phase 1: pass your evals

**Run evals** on the suite targets the candidate. The eval gate shows the latest completed candidate run with its confidence interval, and goes stale after 14 days or when a case changes after the run.

## Phase 2: shadow real traffic

Gateway mirrors the sampled share of requests that resolve to your current model, calling the candidate after customers get the current model's response. Sampling is per session, so a sampled conversation is mirrored on every turn.

**Live traffic comparison** shows request counts, success rates, cost, tokens, latency, and paired per-request responses for both models. Pause, resume, or change sampling from the migration header.

## Phase 3: complete the cutover

**Complete** lists the routing policies that reference your current model, pre-selected, with each one's scope and whether the model appears in its tag rules; uncheck any to leave alone. Completing rewrites the selected policies (up to 50) to the candidate, merging it with any existing entry, and fails if your organization's restrictions block the candidate. Unchecked policies and requests that name the old model directly are unchanged. A gate that isn't green asks you to acknowledge it and optionally add a note, but never blocks you.

## Reverting

Reverting restores the rewritten policies, skipping any edited since the cutover and noting them in the timeline. A reverted migration can't restart; create a new one. The timeline records state and sampling changes, the verdict at completion, per-policy outcomes, and notes. Automate the lifecycle with the [migrations endpoints](/merge-gateway/evals/evals-api#migrations).

## Next steps

#### [Evals](/merge-gateway/evals/overview)

Build the suite that gates your migration

#### [Runs and monitoring](/merge-gateway/evals/running-evals)

Trials, confidence intervals, and run comparison

#### [Routing policies](/merge-gateway/routing/overview)

The policies a completion rewrites