---
title: "Plan a multi-provider flight search without dispatching"
method: POST
path: "/wrapped/credits/locus-travel/flight-search/preview"
tags: ["Travel routing"]
---

# Plan a multi-provider flight search without dispatching

`POST /wrapped/credits/locus-travel/flight-search/preview`

## Request

- Base URL: `https://api.paywithlocus.com/api`
- URL: `https://api.paywithlocus.com/api/wrapped/credits/locus-travel/flight-search/preview`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

Feature-gated Locus Travel planning route. It validates the normalized search, applies credential and catalog restrictions, selects eligible providers, and returns the aggregate estimated charge. It does not contact travel providers or burn credits. estimateExact is false when at least one selected provider has a live or otherwise variable price.

## Headers

- `X-Locus-Session-Id` string
- `X-Locus-End-User` string: Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address.

## Request body

- TravelFlightSearchRequest: Preferred and excluded values cannot overlap. minLayoverMinutes cannot exceed maxLayoverMinutes. Defaults are selected from optimize when optional depth controls are absent.
  - `origin` string, required: IATA code or place name. Three-letter codes are normalized to uppercase.
  - `destination` string, required: Must differ from origin.
  - `departureDate` string, date, required: Real calendar date in YYYY-MM-DD form.
  - `returnDate` string, date: Optional return date on or after departureDate.
  - `adults` integer
  - `children` integer
  - `infants` integer: Cannot exceed adults. Total travelers cannot exceed nine.
  - `cabinClass` 'economy' | 'premium_economy' | 'business' | 'first'
  - `currency` string
  - `optimize` string[]: Cost favors fewer inexpensive sources, quality increases depth, and context favors compact agent-readable output.
  - `preferredAirlines` string[]
  - `excludedAirlines` string[]
  - `preferredAirports` string[]
  - `excludedAirports` string[]
  - `maxStops` integer
  - `minLayoverMinutes` integer
  - `maxLayoverMinutes` integer
  - `maxDurationMinutes` integer
  - `maxPrice` number: Maximum itinerary price in currency.
  - `departAfter` string
  - `departBefore` string
  - `arriveAfter` string
  - `arriveBefore` string
  - `maxResults` integer
  - `maxProviders` integer
  - `providers` string[]: Optional explicit provider selection, still narrowed by credential, catalog, availability, and request compatibility.
  - `maxCredits` union: Aggregate no-dispatch ceiling for all selected child calls, in account credits.
    - string
    - number
  - `externalUserId` string: Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address.
  - `attribution` object: Optional JSON attribution copied to child calls.

## Response `200`

No-dispatch provider plan and aggregate estimate

- TravelFlightSearchPreview
  - `object` 'locus.travel_flight_search.preview', required
  - `capability` 'travel.flight_search', required
  - `request` TravelFlightSearchRequest, required: Preferred and excluded values cannot overlap. minLayoverMinutes cannot exceed maxLayoverMinutes. Defaults are selected from optimize when optional depth controls are absent.
    - `origin` string, required: IATA code or place name. Three-letter codes are normalized to uppercase.
    - `destination` string, required: Must differ from origin.
    - `departureDate` string, date, required: Real calendar date in YYYY-MM-DD form.
    - `returnDate` string, date: Optional return date on or after departureDate.
    - `adults` integer
    - `children` integer
    - `infants` integer: Cannot exceed adults. Total travelers cannot exceed nine.
    - `cabinClass` 'economy' | 'premium_economy' | 'business' | 'first'
    - `currency` string
    - `optimize` string[]: Cost favors fewer inexpensive sources, quality increases depth, and context favors compact agent-readable output.
    - `preferredAirlines` string[]
    - `excludedAirlines` string[]
    - `preferredAirports` string[]
    - `excludedAirports` string[]
    - `maxStops` integer
    - `minLayoverMinutes` integer
    - `maxLayoverMinutes` integer
    - `maxDurationMinutes` integer
    - `maxPrice` number: Maximum itinerary price in currency.
    - `departAfter` string
    - `departBefore` string
    - `arriveAfter` string
    - `arriveBefore` string
    - `maxResults` integer
    - `maxProviders` integer
    - `providers` string[]: Optional explicit provider selection, still narrowed by credential, catalog, availability, and request compatibility.
    - `maxCredits` union: Aggregate no-dispatch ceiling for all selected child calls, in account credits.
      - string
      - number
    - `externalUserId` string: Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address.
    - `attribution` object: Optional JSON attribution copied to child calls.
  - `providers` object[], required
    - `providerId` string, required
    - `providerName` string, required
    - `estimatedCostCredits` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `priceExact` boolean, required
    - `estimatedCostUsd` number: Shown only to secret-key and dashboard principals.
  - `eligibleProviders` object[], required
    - `providerId` string, required
    - `providerName` string, required
  - `ineligibleProviders` TravelIneligibleProvider[], required
    - `providerId` string, required
    - `providerName` string, required
    - `reason` 'credential_scope' | 'provider_disabled' | 'provider_filtered' | 'provider_unavailable' | 'request_unsupported', required
    - `detail` string
  - `estimatedCostCredits` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
  - `estimateExact` boolean, required
  - `estimatedCostUsd` number: Shown only to secret-key and dashboard principals.

## Other responses

- `400`: Invalid flight search
- `401`: Missing or invalid execution credential
- `403`: Account, end-user, Agent Connection, or endpoint policy denied access
- `409`: The planned provider calls exceed maxCredits or another credential-level charge ceiling

---

[API](https://skmtc.dev/paywithlocus/apis/locus-pro-api.md) - [All operations](https://skmtc.dev/paywithlocus/apis/locus-pro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paywithlocus/apis/locus-pro-api/revisions/aab8fa5d6cef?raw)