Searchapi

Google Flights Round Trip

google_flights_round_trip

Read-only

Search round-trip Google Flights with airline, time, price, and booking details.

Required on every call, including token follow-ups: departure_id, arrival_id, outbound_date, return_date. Preserve all original search options, including travel_class, passenger counts, currency, and filters.

Workflow:

Search for outbound flights.
Repeat the arguments with the chosen outbound flight's departure_token to retrieve return options.
Repeat the arguments, replacing departure_token with the chosen return flight's booking_token to retrieve booking details.

One-way: google_flights_one_way. Flexible dates: google_flights_calendar_round_trip.

Input Schema

TableJSON Schema

Name	Required	Description
`gl`	No	ISO 3166-1 alpha-2 country code in lowercase (e.g., 'us', 'gb', 'de'). Affects pricing and flight availability. Default: us.
`stops`	No	Maximum stops filter: nonstop (direct only), one_stop_or_fewer (at most 1 stop), two_stops_or_fewer (at most 2 stops), any (no limit). Use the named value (e.g. 'two_stops_or_fewer'), not a bare number like '2'. Default: any.
`adults`	No	Number of adults (1-9). Default: 1.
`sort_by`	No	Sort order. Default: top_flights.
`children`	No	Number of children (0-9). Default: 0.
`currency`	No	Currency code (ISO 4217, e.g., 'USD', 'EUR', 'GBP'). Default: USD.
`max_price`	No	Maximum price filter. Flights above this price (in the specified currency) are excluded.
`arrival_id`	Yes	IATA airport code (e.g., 'LAX') or kgmid (e.g., '/m/030qb3t' for Los Angeles). City names must first be converted using google_flights_location_search.
`return_date`	Yes	Return departure date in YYYY-MM-DD format (ISO 8601). Required.
`checked_bags`	No	Number of checked bags (0-9). Shows prices with checked bag fees included. Cannot exceed total passenger count.
`departure_id`	Yes	IATA airport code (e.g., 'JFK') or kgmid (e.g., '/m/02_286' for New York). City names must first be converted using google_flights_location_search.
`travel_class`	No	Travel class: economy, premium_economy, business, first_class. Default: economy.
`booking_token`	No	Token from the selected return flight for retrieving booking details. Replaces departure_token.
`carry_on_bags`	No	Number of carry-on bags (0-9). Shows prices with carry-on fees included for budget airlines. Cannot exceed total passenger count.
`outbound_date`	Yes	Outbound departure date in YYYY-MM-DD format (ISO 8601). Required.
`infants_on_lap`	No	Number of infants on lap (0-9). Default: 0.
`departure_token`	No	Token from the selected outbound flight for retrieving return options.
`infants_in_seat`	No	Number of infants in seat (0-9). Default: 0.
`excluded_airlines`	No	Comma-separated IATA airline codes to exclude (e.g., 'NK,F9').
`included_airlines`	No	Comma-separated IATA airline codes to include (e.g., 'AA,UA,DL').
`max_flight_duration`	No	Maximum total flight duration in minutes (e.g., 600 for 10 hours). Excludes flights exceeding this duration.
`exclude_basic_economy`	No	Set to true to exclude Basic Economy fares, the cheapest and most restrictive ones. Only valid with travel_class economy. Google Flights offers this filter for flights within the US, its territories and Canada; on other routes results are unchanged.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 18, 2026

addedInput schema / properties / exclude_basic_economy

Added value: +{
+  "description": "Set to true to exclude Basic Economy fares, the cheapest and most restrictive ones. Only valid with travel_class economy. Google Flights offers this filter for flights within the US, its territories and Canada; on other routes results are unchanged.",
+  "type": "boolean"
+}

Changed2 schema fields changedSep 10, 2026

changedInput schema / properties / booking_token / description

Previous value: -"Token for retrieving booking details. Pass this after selecting both outbound and return flights. Found in the booking_token field of flight results."New value: +"Token from the selected return flight for retrieving booking details. Replaces departure_token."

changedInput schema / properties / departure_token / description

Previous value: -"Token from a selected outbound flight. Pass this to view return flight options. Found in the departure_token field of outbound flight results."New value: +"Token from the selected outbound flight for retrieving return options."

Changed2 schema fields changedJun 17, 2026

changedInput schema / properties / stops / description

Previous value: -"Maximum stops filter. Default: any."New value: +"Maximum stops filter: nonstop (direct only), one_stop_or_fewer (at most 1 stop), two_stops_or_fewer (at most 2 stops), any (no limit). Use the named value (e.g. 'two_stops_or_fewer'), not a bare number like '2'. Default: any."

changedInput schema / properties / travel_class / description

Previous value: -"Travel class. Default: economy."New value: +"Travel class: economy, premium_economy, business, first_class. Default: economy."

Changed1 schema field changedJun 10, 2026
- addedInput schema / $schema
```
Added value: +"https://json-schema.org/draft/2020-12/schema"
```

Changed1 schema field changedMar 16, 2026

changedInput schema / properties / gl / description

Previous value: -"Country code (ISO 3166-1 alpha-2, e.g., 'us', 'gb', 'de'). Affects pricing and flight availability. Default: us."New value: +"ISO 3166-1 alpha-2 country code in lowercase (e.g., 'us', 'gb', 'de'). Affects pricing and flight availability. Default: us."

First observedFeb 18, 2026

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: the multi-step token-based workflow and the instruction to preserve all original search options. It does not disclose error conditions or response format, but given the annotations, this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a concise purpose sentence, a bolded requirement line, a numbered workflow, and a final alternatives line. It is front-loaded with essential information and contains no filler. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 22 parameters and a multi-step workflow, the description covers the required inputs, the token usage, and the routing to sibling tools. It does not explain output format, but that is not necessary given no output schema. The description is sufficient for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is documented. The description adds meaning by highlighting the required parameters for every call and explaining the roles of departure_token and booking_token in the workflow. It also emphasizes preserving options, which goes beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Search'), resource ('round-trip Google Flights'), and what it returns ('airline, time, price, and booking details'). It also explicitly names sibling alternatives (one-way, calendar) to differentiate itself. This clearly distinguishes it from related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a numbered workflow (search outbound, then return, then booking) and explicitly names alternatives: 'One-way: google_flights_one_way. Flexible dates: google_flights_calendar_round_trip.' This gives clear when-to-use guidance and exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Searchapi tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?