---
title: "Search flights across selected providers"
method: POST
path: "/wrapped/credits/locus-travel/flight-search"
tags: ["Travel routing"]
---

# Search flights across selected providers

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

## Request

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

Feature-gated system-managed capability router. Locus plans eligible providers, executes them concurrently, normalizes and deduplicates itineraries, ranks offers, and returns aggregate billing. Use the preview route first when you need an estimate. A narrower request maxCredits or credential-level ceiling prevents dispatch when the aggregate estimate is too high. Retries must reuse the same Idempotency-Key and identical logical request; a 202 response means one or more child providers are still processing, so retry with the same key.

## Headers

- `X-Locus-Session-Id` string
- `Idempotency-Key` string, required
- `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`

Normalized, ranked flight search with provider outcomes and aggregate billing

- TravelFlightSearchResponse
  - `object` 'locus.travel_flight_search', required
  - `capability` 'travel.flight_search', required
  - `routerVersion` string, required
  - `runId` string, uuid, required
  - `search` 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.
  - `appliedOptimizations` string[], required
  - `partial` boolean, required: True when at least one selected provider did not produce a complete successful result.
  - `warnings` string[], required
  - `providers` TravelProviderOutcome[], required
    - `providerId` string, required
    - `providerName` string, required
    - `status` 'succeeded' | 'failed' | 'pending', required
    - `latencyMs` number, required
    - `itineraryCount` integer, required
    - `surfacedItineraryCount` integer, required
    - `uniqueSurfacedItineraryCount` integer, required
    - `tailLatencyContributionMs` number, required
    - `chargedCredits` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `errorCode` string
    - `estimatedCostUsd` number
  - `itineraries` TravelItinerary[], required
    - `id` string, required
    - `score` number, required
    - `providerItineraryId` string: Provider-native itinerary ID when one canonical source supplies it.
    - `legs` TravelLeg[], required
      - `origin` TravelPlace, required
        - `code` string, required
        - `name` string
        - `city` string
      - `destination` TravelPlace, required
        - `code` string, required
        - `name` string
        - `city` string
      - `departure` string, required
      - `arrival` string, required
      - `durationMinutes` integer
      - `stopCount` integer, required
      - `segments` TravelSegment[], required
        - `origin` TravelPlace, required
          - `code` string, required
          - `name` string
          - `city` string
        - `destination` TravelPlace, required
          - `code` string, required
          - `name` string
          - `city` string
        - `departure` string, required: Provider-normalized departure timestamp.
        - `arrival` string, required: Provider-normalized arrival timestamp.
        - `durationMinutes` integer
        - `flightNumber` string
        - `marketingCarrier` object
          - `code` string
          - `name` string
        - `operatingCarrier` object
          - `code` string
          - `name` string
        - `aircraft` string
      - `intermediateAirports` TravelPlace[]
        - `code` string, required
        - `name` string
        - `city` string
      - `layoverDurationsMinutes` integer[]
    - `offers` TravelOffer[], required
      - `amount` number, required
      - `currency` string, required
      - `formatted` string
      - `bookingUrl` string, uri
      - `linkType` 'booking' | 'search_handoff'
      - `seller` string
      - `cabinClass` 'economy' | 'premium_economy' | 'business' | 'first'
      - `refundable` boolean
      - `providerId` string, required
      - `providerName` string, required
    - `tags` string[], required
    - `selfTransfer` boolean
    - `baggage` string
    - `seatsRemaining` integer
    - `confidence` object, required
      - `score` number, required
      - `sourceCount` integer, required
      - `scheduleAgreement` 'single_source' | 'corroborated', required
      - `priceSpreadPercent` number
    - `sources` object[], required
      - `providerId` string, required
      - `providerName` string, required
      - `rank` integer, required
      - `providerItineraryId` string
    - `sourceCount` integer, required
    - `bookability` object, required
      - `status` 'booking_link_available' | 'search_handoff_available' | 'price_only', required
      - `offerCount` integer, required
      - `bookingLinkOfferCount` integer, required
      - `searchHandoffOfferCount` integer, required
      - `cheapestBookableAmount` number
      - `currency` string, required
  - `itineraryCount` integer, required
  - `bookability` object, required
    - `bookableItineraryCount` integer, required
    - `searchHandoffItineraryCount` integer, required
    - `bookingLinkOfferCount` integer, required
    - `searchHandoffOfferCount` integer, required
    - `offerCount` integer, required
  - `feedback` object, required
    - `method` 'POST', required
    - `route` string, required
    - `runId` string, uuid, required
  - `billing` object, required
    - `chargedCredits` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `successfulProviders` integer, required
    - `attemptedProviders` integer, required

## Other responses

- `202`: The durable run is still processing; retry with the same Idempotency-Key
- `400`: Invalid search, missing/invalid Idempotency-Key, or caller-correctable request error
- `401`: Missing or invalid execution credential
- `403`: Account, end-user, Agent Connection, catalog, or endpoint policy denied execution
- `409`: Idempotency-Key belongs to a different request or the planned aggregate charge exceeds a ceiling
- `503`: All selected travel providers failed; per-provider outcomes and any incurred child billing are returned. X-Locus-Origin-Status: 502.

---

[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)