Seats.aero Award Flight Search

Search award flight availability across 24 mileage programs using the seats.aero partner API.

Setup

Before searching, you need a seats.aero API key:

1. 1. If the user hasn't provided an API key, prompt them:

- "Please provide your seats.aero API key. You can get one at https://seats.aero/partner"

1. 2. Store the key in conversation context for subsequent requests
2. All requests require the header: INLINECODE0

Core Capabilities

1. Search Routes (/search)

Search cached availability across all mileage programs for a specific origin-destination pair.

2. Bulk Availability (/availability)

Explore all availability from a single mileage program, optionally filtered by region.

3. Route Discovery (/routes)

Get all routes monitored for a specific mileage program.

4. Trip Details (/trips/{id})

Get detailed flight segments and booking links for a specific availability.

Quick Reference

Item	Value
Base URL	INLINECODE5
Auth Header

Partner-Authorization: Bearer {key} | | Date Format | YYYY-MM-DD |

Cabin Codes

• - Y = Economy
• INLINECODE9 = Premium Economy
• INLINECODE10 = Business
• INLINECODE11 = First

Regions

North America, South America, Europe, Africa, Middle East, Asia, Oceania

Supported Programs

CODEBLOCK0

Common Workflows

Find availability on a specific route

User: "Find business class SFO to Tokyo next month"

1. 1. Use /search endpoint with:

- origin_airport=SFO - destination_airport=NRT,HND (both Tokyo airports) - cabin=J - start_date and end_date for the date range

Explore program availability

User: "What United awards are available from Europe?"

1. 1. Use /availability endpoint with:

- source=united - INLINECODE20

Get booking details

User: "Show me details for that flight"

1. 1. Use /trips/{id} with the availability ID from previous search
2. Response includes flight segments, times, and booking links

Check what routes a program covers

User: "What routes does Aeroplan monitor?"

1. 1. Use /routes endpoint with INLINECODE23

API Parameters Quick Guide

/search

Parameter	Required	Description
originairport	Yes	3-letter IATA code
destinationairport

Yes | 3-letter IATA code(s), comma-separated |

| cabin | No | Y, W, J, or F (comma-separated for multiple) | | start_date | No | YYYY-MM-DD | | end_date | No | YYYY-MM-DD | | sources | No | Program name(s), comma-separated | | only_direct | No | true/false | | take | No | Results per page (default 100) | | cursor | No | Pagination cursor |

/availability

Parameter	Required	Description
source	Yes	Single program name
cabin

No | Single cabin code |

| origin_region | No | Filter by origin region | | destination_region | No | Filter by destination region | | start_date | No | YYYY-MM-DD | | end_date | No | YYYY-MM-DD | | take | No | Results per page |

Script Usage

For complex or repeated searches, use the Python helper:

CODEBLOCK1

See scripts/seats_api.py for full API client implementation.

Response Handling

Availability Object Fields

• - ID - Use for /trips/{id} lookup
• INLINECODE27 - Origin-Destination pair
• INLINECODE28 - Flight date
• INLINECODE29, WAvailable, JAvailable, FAvailable - Boolean availability
• INLINECODE33, etc. - Points required per cabin
• INLINECODE34, etc. - Number of direct flights available
• INLINECODE35 - Program name
• INLINECODE36 - Data freshness timestamp

Error Handling

• - 401: Invalid or missing API key
• 429: Rate limited, wait and retry
• 404: No results or invalid availability ID

Tips

1. 1. Date ranges: Keep to 30-60 days for faster results
2. Multiple cabins: Search J,F together for premium options
3. Direct flights: Use only_direct=true to filter connections
4. Pagination: Use cursor from response for more results
5. Data freshness: Check ComputedLastSeen - older data may be stale

Reference Documentation

For complete API specification including all fields and response schemas, see references/api-spec.md.