Searches for flights between airports or cities. Not for flight status, price tracking, visa information, bookings, or reservation management.
Polling flow:
1. First call with newSearch → creates search session, returns searchId immediately (status: "created", pollAgainInSeconds: 5).
2. Wait pollAgainInSeconds, then call again with searchId → returns flight results with status "incomplete" (cheaper fares still arriving, pollAgainInSeconds says when to call again) or "complete" (final results).
3. While status is "incomplete", wait pollAgainInSeconds and call again. Stop when status is "complete". If it is still "incomplete" after 3 reads, use the results you have.
A search is complete about 30 seconds after it is created. After that, every read (another page, new filters or sorting) returns status "complete" at once.
Parameters:
- newSearch: Route (from/to as IATA codes), dates (fromDate, toDate in YYYY-MM-DD), passengers, and cabin class. Omit toDate for one-way trips.
- Defaults when not specified: 1 adult, 0 children, 0 infants, economy cabin.
- filters: Include only when the user mentions specific preferences (airlines, stops, times, price range, etc.).
- sorting: A single string value. Options: score_desc (recommended, default), price_asc (cheapest), duration_asc (fastest), leg1_departure_time_asc/desc (outbound departure), leg2_departure_time_asc/desc (return departure, round-trip only).
- page, pageSize: Which page of the ranked trips a searchId read returns. page 1-100 (default 1), pageSize 1-50 (default 20). Out-of-range values are rejected.
Paging: every searchId read returns metadata {page, pageSize, resultCount, totalCandidates, hasMore}. totalCandidates counts trips matching the filters across all pages; resultCount counts this page. For more trips, repeat the searchId with the same filters and sorting and page + 1 while hasMore is true. Featured trips appear on page 1 only, and labels (best_value, cheapest, cheapest_direct) are judged over all matching trips, not the page.
Filter options: a page-1 read with searchId returns filterOptions with the airlines, alliances, bookingSites and stopoverAirports found in this search; page 2 and later do not. While status is "incomplete" the lists are partial and can grow; when status is "complete" they are final. Each entry is { code, name, price }, where price is the cheapest per-person price in the search currency, before filters. Every code is a valid value for the filter of the same name. Use these codes in filters on the next read instead of guessing.
Time filtering (two approaches, mutually exclusive per dimension):
1. Time blocks (6-hour windows) — for broad preferences:
- Options: "midnight" (12am-6am), "morning" (6am-12pm), "afternoon" (12pm-6pm), "night" (6pm-12am)
- Example: outboundDepartureTimeBlocks: ["morning", "afternoon"] = depart before 6pm
2. Time ranges (minute precision) — for specific time requests:
- Format: {min: minutesFromMidnight, max: minutesFromMidnight}, range 0-1440
- Example: "flights after 10pm" → outboundDepartureTimeRange: {min: 1320, max: 1440}
- Example: "depart 8am-1pm" → outboundDepartureTimeRange: {min: 480, max: 780}
- Supports wraparound: {min: 1380, max: 60} = 11pm-1am (crosses midnight)
Time blocks and time ranges cannot both be specified for the same dimension (e.g., outboundDeparture).
Refinement: Provide the searchId from a previous response with updated filters or sorting. Refinement replaces all previous filters and sorting entirely — include existing values alongside new ones to preserve them.
Example — changing return to after 10pm while keeping existing airlines ["SQ", "KE"], outbound 6am-8am, and price_asc sorting:
{ "searchId": "abc", "filters": { "airlines": ["SQ", "KE"], "outboundDepartureTimeRange": { "min": 360, "max": 480 }, "inboundArrivalTimeRange": { "min": 1320, "max": 1440 } }, "sorting": "price_asc" }
Default behavior:
- One date provided → one-way trip
- Return date mentioned → round-trip
- No preferences stated → omit filters
- Specific time requested (e.g., "after 10pm") → use time range
- Broad time preference (e.g., "morning flights") → use time blocks
View input schema
{
"type": "object",
"properties": {
"searchId": {
"type": "string",
"description": "Reuse the searchId from a previous search when refining, filtering, sorting, or selecting."
},
"newSearch": {
"type": "object",
"properties": {
"from": {
"type": "string",
"minLength": 1,
"description": "Departure IATA code (required for a new search when searchId is omitted)."
},
"to": {
"type": "string",
"minLength": 1,
"description": "Arrival IATA code (required for a new search when searchId is omitted)."
},
"fromDate": {
"type": "string",
"minLength": 1,
"description": "Departure date in YYYY-MM-DD (required for a new search when searchId is omitted)."
},
"toDate": {
"type": "string",
"description": "Return date in YYYY-MM-DD for round-trip searches. Omit entirely for one-way trips (do not send null or empty string)."
},
"adultsCount": {
"type": "number",
"minimum": 1,
"maximum": 9,
"default": 1,
"description": "Number of adult passengers (18+). Default: 1. Example: 'my wife and I' = 2 adults"
},
"childrenCount": {
"type": "number",
"minimum": 0,
"maximum": 8,
"default": 0,
"description": "Number of child passengers (2-17). Default: 0. Example: 'with my 5-year-old' = 1 child"
},
"infantsCount": {
"type": "number",
"minimum": 0,
"maximum": 8,
"default": 0,
"description": "Number of infant passengers (under 2 years). Default: 0. Typically on parent's lap"
},
"cabinClass": {
"type": "string",
"enum": [
"economy",
"premium_economy",
"business",
"first"
],
"description": "Requested cabin class for the search",
"default": "economy"
}
},
"required": [
"from",
"to",
"fromDate"
],
"additionalProperties": false,
"description": "Parameters required to create a new flight search when searchId is not provided. Include route (from/to), travel dates (fromDate/toDate in YYYY-MM-DD), and passenger counts. Use this to start a new Wego metasearch; omit when refining/polling an existing search via searchId."
},
"filters": {
"type": "object",
"properties": {
"airlines": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2,
"description": "2-letter IATA airline code"
},
"description": "2-letter IATA airline codes. e.g. ['SQ', 'UA', 'LH']"
},
"alliances": {
"type": "array",
"items": {
"type": "string",
"enum": [
"star_alliance",
"oneworld",
"skyteam"
]
},
"description": "Airline alliances. e.g. ['star_alliance', 'oneworld', 'skyteam']"
},
"stops": {
"type": "array",
"items": {
"type": "number",
"description": "Number of stops"
},
"description": "Number of stops. e.g. Direct flight = 0, 1 stop = [1], direct or 1 stop = [0, 1]"
},
"flightExperiences": {
"type": "array",
"items": {
"type": "string",
"enum": [
"no_overnight_flight",
"no_long_stopover"
]
},
"description": "Flight experience preferences. e.g. ['no_overnight_flight', 'no_long_stopover']"
},
"originAirports": {
"type": "array",
"items": {
"type": "string",
"description": "Departure IATA airport code"
},
"description": "Filter by specific departure airports. e.g. ['JFK']"
},
"destinationAirports": {
"type": "array",
"items": {
"type": "string",
"description": "Arrival IATA airport code"
},
"description": "Filter by specific arrival airports. e.g. ['CDG']"
},
"stopoverAirports": {
"type": "array",
"items": {
"type": "string",
"description": "Stopover/Transit IATA airport code"
},
"description": "Include flights with layovers at these airports. e.g. ['DXB']"
},
"priceRange": {
"type": "object",
"properties": {
"min": {
"type": "number",
"description": "Minimum price per person"
},
"max": {
"type": "number",
"description": "Maximum price per person"
}
},
"additionalProperties": false,
"description": "Budget filter (e.g., 'under $500' = {max: 500}). Per-person price in user's currency."
},
"outboundDepartureTimeBlocks": {
"type": "array",
"items": {
"type": "string",
"enum": [
"midnight",
"morning",
"afternoon",
"night"
]
},
"description": "Filter outbound departure times. Use this to specify when you want to depart on the outgoing flight. e.g. ['morning', 'afternoon'] for departures before 6pm"
},
"outboundArrivalTimeBlocks": {
"type": "array",
"items": {
"$ref": "#/properties/filters/properties/outboundDepartureTimeBlocks/items"
},
"description": "Filter outbound arrival times. Use this to specify when you want to arrive at your destination. e.g. ['morning', 'afternoon'] for arrivals before 6pm"
},
"inboundDepartureTimeBlocks": {
"type": "array",
"items": {
"$ref": "#/properties/filters/properties/outboundDepartureTimeBlocks/items"
},
"description": "Filter return flight departure times for ROUND-TRIP searches. Use this to specify when you want the return leg to depart. e.g. ['morning', 'afternoon'] for departures before 6pm"
},
"inboundArrivalTimeBlocks": {
"type": "array",
"items": {
"$ref": "#/properties/filters/properties/outboundDepartureTimeBlocks/items"
},
"description": "Filter return flight arrival times for ROUND-TRIP searches. Use this to specify when you want the return leg to arrive back. e.g. ['morning', 'afternoon'] for arrivals before 6pm"
},
"outboundDepartureTimeRange": {
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 0,
"maximum": 1439,
"description": "Start time in minutes from midnight (0-1439). Example: 480 = 8:00 AM"
},
"max": {
"type": "integer",
"minimum": 0,
"maximum": 1440,
"description": "End time in minutes from midnight (0-1440). Example: 780 = 1:00 PM. Supports max=1440 for end-of-day (midnight). For midnight wraparound (e.g., 11pm-1am), max can be less than min."
}
},
"required": [
"min",
"max"
],
"additionalProperties": false,
"description": "Granular outbound departure time range in minutes from midnight. Use this for precise time filtering (e.g., {min: 480, max: 780} for 8:00 AM - 1:00 PM). Cannot be used with outboundDepartureTimeBlocks."
},
"outboundArrivalTimeRange": {
"$ref": "#/properties/filters/properties/outboundDepartureTimeRange",
"description": "Granular outbound arrival time range in minutes from midnight. Use this for precise time filtering. Cannot be used with outboundArrivalTimeBlocks."
},
"inboundDepartureTimeRange": {
"$ref": "#/properties/filters/properties/outboundDepartureTimeRange",
"description": "Granular return departure time range in minutes from midnight for ROUND-TRIP searches. Cannot be used with inboundDepartureTimeBlocks."
},
"inboundArrivalTimeRange": {
"$ref": "#/properties/filters/properties/outboundDepartureTimeRange",
"description": "Granular return arrival time range in minutes from midnight for ROUND-TRIP searches. Cannot be used with inboundArrivalTimeBlocks."
},
"bookingTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"wego",
"airline"
]
},
"description": "Booking channel - Book on Wego or direct with airline. e.g. ['wego', 'airline']"
},
"bookingSites": {
"type": "array",
"items": {
"type": "string",
"description": "Travel booking site"
},
"description": "Filter by specific travel booking sites. e.g. ['booking.com']"
},
"outboundTotalDurationRange": {
"type": "object",
"properties": {
"min": {
"type": "number",
"description": "Minimum duration in minutes"
},
"max": {
"type": "number",
"description": "Maximum duration in minutes"
}
},
"additionalProperties": false,
"description": "Outbound flight duration filter (e.g., 'under 3 hours' = {max: 180}). Minutes."
},
"inboundTotalDurationRange": {
"type": "object",
"properties": {
"min": {
"type": "number",
"description": "Minimum duration in minutes"
},
"max": {
"type": "number",
"description": "Maximum duration in minutes"
}
},
"additionalProperties": false,
"description": "Return flight duration filter (e.g., 'under 5 hours' = {max: 300}). Minutes. Round-trip only."
}
},
"additionalProperties": false,
"description": "Flight filters to apply. When used with searchId (refinement), filters completely replace the previous filters. To preserve existing filters like airlines or departure times, include them again along with any new filters."
},
"sorting": {
"type": "string",
"enum": [
"score_desc",
"price_asc",
"duration_asc",
"leg1_departure_time_asc",
"leg1_departure_time_desc",
"leg2_departure_time_asc",
"leg2_departure_time_desc"
],
"default": "score_desc",
"description": "Sort order for results. Pass a single string value. Options: score_desc (recommended, default), price_asc (cheapest), duration_asc (fastest), leg1_departure_time_asc/desc (outbound departure), leg2_departure_time_asc/desc (return departure, round-trip only)."
},
"locale": {
"type": "string",
"description": "Locale for results (e.g., 'en', 'ar', 'zh'). If not provided, uses the locale from the user's settings. Supports BCP 47 format (e.g., 'ar-SA' resolves to 'ar')."
},
"currencyCode": {
"type": "string",
"description": "The currency the user pays in, as an ISO 4217 code (e.g. 'SAR', 'INR', 'USD'): the one they ask for, else the currency of their own country (siteCode). Do NOT take it from the destination: a user in India booking Dubai pays in 'INR'. Send the same code on every flight and hotel call in this conversation, searchId reads included."
},
"siteCode": {
"type": "string",
"pattern": "^(?:[A-Z]{2})?$",
"description": "The user's OWN country as an ISO 3166-1 alpha-2 code (e.g. 'SG', 'SA', 'IN'), when the conversation shows where the user is. It picks the Wego site that booking links open and the market prices come from. Do NOT take it from the departure, arrival or hotel city: a user in India searching London is still 'IN'. Omit it when unknown (default 'US'). Set it when the search is created; a searchId read keeps the search's site."
},
"page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 1,
"description": "Page of trips a searchId read returns, 1-based (default 1, max 100)."
},
"pageSize": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 20,
"description": "Trips per page on a searchId read (default 20, max 50). Out-of-range or non-integer values are rejected, never clamped."
}
},
"required": [
"currencyCode"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}