Real-time Search API - Data Retrieval

Overview

Retrieve Real-Time Search Results

Returns the latest results for a previously submitted real-time flight search. Searches run asynchronously, so clients should poll this endpoint with the original task_id until processing is complete.

Each response includes:

• Award availability collected so far

• Completed and pending program-level searches

• Current task status

• Flight, pricing, cabin, and segment details

Results may appear incrementally and may be repeated across polling responses. Use the itinerary identifiers to deduplicate records.

Recommended Sample Code

Real-Time Search API sample code

Request Fields

task_id

• Type: String

• Required: Yes

• Description: Client-assigned identifier used to track the search and retrieve its results.

• Constraint: Must match the task_id supplied in the original real-time search request.

api_key

• Type: String

• Required: Yes

• Description: API key used to authenticate the request.

Task Constraints

A client-defined task_id must be included in the original search request.

A task may include either:

• Up to two travel dates across a maximum of 10 unique loyalty programs; or

• One travel date across all supported loyalty programs.

Clients may poll this endpoint until finish becomes true.

Response Fields

result

Award-flight itineraries collected for the task. Results may be returned incrementally or repeated across polling responses.

Use ids.flight_deduplicate_id to identify and deduplicate equivalent pricing results.

finish

Indicates whether task processing is complete.

• false — One or more program-level searches are still pending. Continue polling.

• true — All searches associated with the task have finished. Stop polling.

finish_reason

Reason task processing ended. This may be unknown while the task is still running.

program_done

Program-level search units that have completed processing.

Each value follows this format:

program|PROGRAM|ORIGIN|DESTINATION|PAX|DATE

Example:

program|VS|JFK|LHR|1:0|20261225

In this example:

• VS — Loyalty-program code

• JFK — Origin airport

• LHR — Destination airport

• 1:0 — Passenger-count encoding used by the search

• 20261225 — Travel date in YYYYMMDD format

A completed program may appear in program_done even when it returned no award availability.

task_left

Program-level search units that are still processing.

missing_keys

Program-level searches for which results are not yet available. These values use the same format as program_done.

task_id

Task identifier associated with the response.

record_id

Internal identifier for the stored task-result record.

time_elapsed

Number of seconds elapsed during result retrieval or task processing.

status

Response status code. A value of 200 indicates that the retrieval request succeeded.

Internal Metadata

frontend_duration, last_request_time, and task_done: are internal metadata. Clients should not rely on these fields.

Result Object Fields

Each object in result represents one award-flight itinerary.

Identification

id — AwardTool identifier for the itinerary and selected cabin.

ids.flight_id — Identifier for the underlying flight itinerary.

ids.flight_deduplicate_id — Identifier that includes the itinerary and pricing information. Use this field to deduplicate results across polling responses.

search_key — Program-level search unit that produced the itinerary.

Flight Summary

date — Travel date in YYYY-MM-DD format.

program_code — Loyalty-program code through which the award can be booked.

airline_code — Code of the airline operating or marketing the itinerary.

airline_name — Name of the airline operating or marketing the itinerary.

cabin_type — Cabin used for the displayed award price.

final_cabin_type — Normalized cabin category assigned to the result.

award_points — Points or miles required for the displayed one-way award.

surcharge — Taxes and carrier-imposed fees associated with the award.

currency — Currency used for cash amounts and surcharges, such as USD.

cash_fare — Available cash fare. A value of -1 indicates that a cash fare was not returned.

seats — Number of award seats available at the displayed price.

seats_from_airline — Seat count reported directly by the loyalty program or airline.

percent_premium — Percentage of in-flight travel time spent in the requested premium cabin.

distance — Total itinerary distance.

last_seen — Unix timestamp indicating when the itinerary was last observed.

return_trip — Indicates whether the itinerary represents a return flight.

url — Airline or loyalty-program website where the award may be booked.

advisory — Notices or restrictions associated with the itinerary.

extra_info — Additional program-specific information.

payment

Summarizes the price of the displayed cabin.

cabin — Cabin associated with the displayed price.

miles — Points or miles required.

tax — Taxes and fees required.

Short fields such as ca, m, t, and c are internal aliases of the canonical payment fields and should be ignored.

transfer_options

Lists supported transferable-points programs that can provide the required loyalty-program currency.

program — Transferable-points program, such as amex, bilt, chase, or citi.

points — Transferable points required after accounting for any applicable transfer bonus.

bonus — Applicable transfer-bonus percentage. This field may be omitted when no bonus applies.

cabin_prices

Contains pricing details for each cabin available on the same itinerary. Cabin names such as Economy, Premium Economy, Business, and First are used as dynamic keys.

Each cabin may contain:

miles — Points or miles required for that cabin.

tax — Taxes and fees required.

cash_price — Available cash price. A value of -1 indicates that no cash price was returned.

seats — Number of award seats available.

premium_cabin_percentage — Percentage of flight time spent in the selected premium cabin.

segments — Cabin assignment and timing summary for each segment.

transfer_options — Transferable-points options available for the cabin price.

Cabin Price Segments

departure — Segment origin airport.

arrival — Segment destination airport.

cabin — Cabin assigned to the segment.

duration — Segment duration in minutes.

layover — Layover following the segment, in minutes.

fare

Contains itinerary-level schedule and duration information.

travel_minutes_total — Total journey duration in minutes, including connections.

travel_time_display — Human-readable journey duration, such as 6h 50m.

day_count — Number of calendar-day changes between departure and arrival.

products — Ordered flight segments that make up the itinerary.

fare.products

Each item in products represents one flight segment.

origin — Origin airport’s IATA code.

destination — Destination airport’s IATA code.

departure_time — Scheduled local departure date and time.

arrival_time — Scheduled local arrival date and time.

airline_code — Operating or marketing airline code.

airline_name — Airline name.

flight_number — Flight number, including the airline code.

aircraft — Scheduled aircraft type.

cabin_type — Cabin assigned to the segment.

show_cabin_type — Cabin label intended for display.

travel_minutes — Segment duration in minutes.

layover_time — Layover following the segment, in minutes.

distance — Segment distance.

Recommended Integration Flow

1. Submit the real-time search using a client-defined task_id.

2. Call this endpoint with the same task_id.

3. Store the records returned in result.

4. Deduplicate records using ids.flight_deduplicate_id.

5. Review program_done and task_left to monitor progress.

6. Continue polling while finish is false.

7. Stop polling when finish becomes true.