Recipe routing

Use a routed Recipe when your application needs results across providers through one request. Locus selects eligible providers, merges their results, and returns sources and a billing receipt. For the full set of outcomes and use cases, start with Recipes. This page covers server-side search and flight routing.

Choose an endpoint

Slug	Result
`router/web-search`	Ranked, deduplicated search results with provider sources
`router/web-research`	Research using a suitable structured source or multi-provider search
`locus-travel/flight-search`	Normalized flight options with source confidence and booking availability

Costs vary with the providers used. These routes charge for successful underlying calls; preview requests are free.

Configure the eligible pool

Open Agent tools → Multi-Provider Web Search to set the provider allowlist, search breadth, and result limit. Providers must also have an enabled catalog access path.

Mode	Search breadth
`fast`	Up to two eligible engines
`balanced`	Up to the selected provider limit; default 4
`comprehensive`	Every eligible engine

Your allowlist is a hard boundary. A request can narrow it further but cannot add providers outside it.

Preview without calling providers

Append /preview to the execution route to see the planned providers and estimated charge:

curl --fail-with-body -X POST \
  "https://api.paywithlocus.com/api/wrapped/credits/router/web-search/preview" \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "recent primary-source announcements about coding agents",
    "mode": "balanced",
    "maxResults": 10
  }'

A preview spends no credits. Availability and prices can change before execution, so pass maxCredits to set an execution-time ceiling.

Run a routed search

curl --fail-with-body -X POST \
  "https://api.paywithlocus.com/api/wrapped/credits/router/web-search" \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY" \
  -H "Idempotency-Key: research-coding-agents-1" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "recent primary-source announcements about coding agents",
    "mode": "balanced",
    "maxResults": 10,
    "maxCredits": "500"
  }'

The main controls are search mode, result count, recency, country, domains, and the credit ceiling. If the estimated charge exceeds maxCredits, Locus rejects the plan before dispatch without charging. Reuse the idempotency key when retrying the same logical request. Use a new key for a new request.

Read the result and receipt

The response includes results, provider outcomes, and billing.chargedCredits. A partial: true response means some providers failed while others produced results. Review those results before requesting more work; successful calls can still be charged. Agents discover these routes through their normal tool search. Connection allowlists and spending limits continue to apply.

Compare flights with Locus Travel

Call locus-travel/flight-search/preview with airports, dates, and preferences. Execute the same body at locus-travel/flight-search with an idempotency key.

{
  "origin": "SFO",
  "destination": "JFK",
  "departureDate": "2026-10-15",
  "adults": 1,
  "cabinClass": "economy",
  "maxStops": 1,
  "maxResults": 5,
  "maxCredits": "500"
}

Results include itineraries, provider sources, warnings, booking availability, and the exact charge. If the route returns 202, retry the same request with the same idempotency key to collect the result. See the API reference for all filters, response fields, and workspace routing settings.

Getting started

Build with Locus Pro

Connect agents

Funding & billing

Developer tools

Catalog directory

Testing

Choose an endpoint

Configure the eligible pool

Preview without calling providers

Run a routed search

Read the result and receipt

Compare flights with Locus Travel

​Choose an endpoint

​Configure the eligible pool

​Preview without calling providers

​Run a routed search

​Read the result and receipt

​Compare flights with Locus Travel

Choose an endpoint

Configure the eligible pool

Preview without calling providers

Run a routed search

Read the result and receipt

Compare flights with Locus Travel