Travel and places · SearchApi (Google Flights)

flights.search

Searches Google Flights between two airports for adults, children, seated infants and lap infants, up to nine passengers. Child ages are not accepted by this source. Results include legs, duration, stops, price and requested passenger counts. For round trips, outbound details supplies return_search parameters; execute that search and request details on the chosen return to get booking options for both legs. Passenger counts are preserved throughout. One-way details returns booking options directly.

Operation: POST /v1/capabilities/flights.search/execute
operationId: executeFlightsSearch
Typical credits: 4
Search deadline: 15 s server-side
Paging: single result
Availability: ConfiguredChecked 2026-09-23 21:02 UTC

Cost basis: $0.004 per search. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/flights.search/execute, JSON, validated against the FlightsSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of flights.search
Field	Type	Required	Default	Constraints and description
origin	string	yes		min length 3, max length 3 IATA airport code.
destination	string	yes		min length 3, max length 3 IATA airport code.
departure_date	string	yes		pattern ^\d{4}-\d{2}-\d{2}$ Outbound date (YYYY-MM-DD).
return_date	string	no		pattern ^\d{4}-\d{2}-\d{2}$ Return date; omit for one-way (YYYY-MM-DD).
departure_token	string	no		min length 1, max length 16384 Outbound selection token supplied by flight details; use with its original round-trip query to list return flights.
adults	integer	no	1	min 1, max 9
children	integer	no	0	min 0, max 8 Child passengers; the provider accepts a count, not individual ages. At most 9 passengers in total.
infants_in_seat	integer	no	0	min 0, max 8
infants_on_lap	integer	no	0	min 0, max 8
cabin	"economy" \| "premium_economy" \| "business" \| "first"	no
max_stops	integer	no		min 0, max 2
currency	string	no	"USD"	min length 3, max length 3

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

At most nine passengers in total (adults, children, infants).
departure_token requires the original round-trip return_date.
return_date must not precede departure_date.

Examples

Return trip

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/flights.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"origin":"LHR","destination":"JFK","departure_date":"2026-11-03","return_date":"2026-11-10","adults":2,"children":1,"cabin":"economy","max_stops":1}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the FlightsSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of flights.search
Key	Type	Presence	Note
price	number	when the source has it
currency	string	always
requested_passengers	object	always
total_duration	string	when the source has it	Formatted, e.g. "5h 30m".
stops	integer	when the source has it
layovers	object[]	when the source has it
departure	string	when the source has it
arrival	string	when the source has it
legs	object[]	always
emissions_kg	number	when the source has it
needs_return_selection	boolean	when the source has it	Round trips: pick the outbound first.

Caveats

Round trips: details on an outbound itinerary returns return_search: { capability, params }; execute that request to list return flights.

Follow-ups

Paging: Single result; more is refused with 400 invalid_request.
Update: not offered.
Record actions:
- details: Booking options, or return_search parameters for an outbound round-trip selection.
Detail behaviour: First details call fetches from the provider (billed as stated); repeats are cached and free. details is a fresh booking-options request: $0.004. For a round trip it may instead return return_search (a typed next request) at no charge.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

`details` detail keys (owned, documented tier)

Either booking options for the itinerary, or (round trips, outbound leg) a typed return_search request at no charge. Built entirely by our code and published as the FlightsSearchDetailsDetail component; the wire contract of detail stays untyped, extra keys may appear.

Detail keys of flights.search details
Field	Type	Required	Default	Constraints and description

Other record detail objects are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/flights.search/execute", {
  body: {
    "origin": "LHR",
    "destination": "JFK",
    "departure_date": "2026-11-03",
    "return_date": "2026-11-10",
    "adults": 2,
    "children": 1,
    "cabin": "economy",
    "max_stops": 1
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);