Perplexity Router API vs Agent API: Which Provides Web Grounding?

First fix the name: Gateway is now Router

The old /docs/gateway/quickstart address currently redirects to /docs/router/quickstart. The page calls the product Perplexity Router API and marks it private preview. Existing articles, bookmarks and implementation notes that still say “Gateway” should record that redirect so readers do not mistake an old label for a separate current product.

Router’s documented base URL is https://api.perplexity.ai/router/v1. It accepts supported OpenAI and Anthropic request shapes, exposes a current model catalog and routes requests to a healthy deployment. Perplexity describes it as direct model access with your own prompts and tools. That is an inference contract, not an automatic web-retrieval contract.

Compare the current product contracts

A Router response can discuss text that your application retrieved and supplied. That may be well evidenced, but Router did not perform the retrieval unless your own tool layer did. An Agent response can use current web evidence, but only the recorded tool configuration and returned result objects establish that a particular run actually searched.

Choose Router for controlled inference

Router fits a service that already owns retrieval, redaction, permissions and context assembly, or that wants compatible access to models through one Perplexity key. The application can freeze a source bundle, pass it to several models and compare reasoning over identical evidence without changing the information available to each run.

Preserve the requested model, endpoint, request schema, full input hash, generation parameters, response model, response identifier, timestamp, usage and raw output. Router says the response echoes the requested model ID and billing uses that model’s published rate regardless of how the request was served. Do not turn “healthy deployment routing” into an unsupported claim that the request switched to a different named model.

If your application adds search or a private corpus, document that layer separately. Record retrieval query, source IDs, access policy, content snapshot or hash, cutoff time and the exact passages supplied. The answer’s evidence contract comes from that application-controlled record—not from Router compatibility with an OpenAI or Anthropic SDK.

Choose Agent API for integrated web tools

The Agent API endpoint is POST https://api.perplexity.ai/v1/agent; Perplexity also accepts /v1/responses as an OpenAI-compatible alias. Its web-search documentation says to add {"type":"web_search"} to the request’s tools array. fetch_url retrieves the content of a known page. Presets can package models, tool access, token limits and other settings.

For a current-web question, record the tool array or preset name, search filters, instructions, maximum tool calls, returned model, tool invocations, result IDs, canonical URLs, cost and latency. Perplexity notes that inline citation markers are prompt-dependent. The returned search_results IDs and URLs are the source of truth, so store those objects even when the prose contains neat bracketed citations.

Download the grounding run ledger

The Perplexity grounding run ledger (CSV) is a 24-field control record for Router and Agent experiments. It separates product, endpoint, request schema, model or preset, context mode, tool configuration, search filters, evidence cutoff, returned sources, claim-source review, cost, latency and decision.

Four rows labelled EXAMPLE-REMOVE show distinct contracts: Router with frozen supplied context, Agent with web search, Agent without tools, and a preset-managed Agent run. Remove them before collecting production data. Never store an API key, authorization header or confidential prompt content in the CSV.

Use explicit decision values

• Accept as controlled inference: the evidence bundle was frozen and identical across compared runs.
• Accept as grounded candidate: search ran and returned identifiable sources; claim review is still required.
• Reject as grounding test: a current-web question ran without retrieval evidence.
• Inconclusive: source results were unavailable, a fallback changed the contract, or critical request fields were not retained.

Run two studies, not one unfair bake-off

A current-events question sent to Router without supplied current evidence is not comparable to an Agent run allowed to search. That test changes both the model path and the available information. It can tell you which complete application answered better, but it cannot isolate model quality or retrieval quality.

Study 1: frozen-context inference

1. Create a time-stamped evidence bundle from permitted primary sources.
2. Hash or version the bundle and give every tested system the same relevant passages.
3. Disable additional retrieval or record any unavoidable retrieval separately.
4. Score factual entailment, completeness, instruction following, latency and cost.
5. Repeat across a declared question set and report denominators, not anecdotes.

Study 2: current-web workflow

1. Define the current question, recency requirement and acceptable source classes.
2. Configure Agent web tools or a documented grounded preset.
3. Save every returned result ID and URL before judging the prose.
4. Open sources and score retrieval coverage, source quality and claim-level entailment.
5. Record tool-call cost, token cost, latency, failures and fallback behavior.

Report these studies separately. The first compares inference over controlled evidence. The second evaluates the whole research workflow, including retrieval decisions and citation quality.

Treat model fallback as a reproducibility event

Agent API supports a models array as an ordered fallback chain. Perplexity documents trying models in order until one succeeds and returning a model field for the model used. Preserve both the requested chain and returned model. A successful fallback improves availability but changes the system under test.

Do not infer fallback solely from an unexpected answer style. Use the response model and error trail. Also snapshot the model catalog or documentation date because available routes and names change.

Review citations at the claim level

1. Split the answer into material factual claims.
2. Map each claim to one or more returned result IDs.
3. Open the canonical source and confirm that it supports the claim’s scope, date and subject.
4. Distinguish a source statement from the model’s inference.
5. Mark unsupported, contradictory, stale, inaccessible and secondary-only evidence.
6. Retain the final reviewed answer beside the unedited response.

The citation-ready passage test provides a compact entailment review. The evidence-led publishing guide expands this into a source ledger and skeptical editorial pass.

A saved URL list is not enough for volatile evidence. When permitted, retain the retrieved excerpt or a content hash with the access time, because a page can change after the run and make later citation review ambiguous.

Original-work boundary: Search Engine Answer has not run a paid Router-versus-Agent benchmark for this revision. The comparison above is a product-contract analysis of current Perplexity documentation plus a reusable test design; it does not claim measured model superiority.

Implementation checklist

• Replace “Gateway API” with the current “Router API” name while retaining redirect history in migration notes.
• Confirm Router private-preview access before designing around it.
• Choose who owns retrieval, context permissions and source retention.
• Record the exact endpoint, request schema, model or preset and tools for every run.
• For Agent web research, save returned result IDs and URLs; do not rely only on inline markers.
• Separate frozen-context inference scores from current-web workflow scores.
• Record the returned model and isolate fallback runs.
• Keep keys, authorization headers and confidential prompt data out of the public ledger.
• Recheck the current model catalog, pricing and documentation before release.

Primary documentation

• Perplexity Router API quickstart
• Perplexity Agent API quickstart
• Perplexity Agent API: Web Search tool
• Perplexity Agent API: Model fallback
• Perplexity Agent API: OpenAI compatibility