| name | award-calendar |
| description | Find the cheapest award dates for a route over a date range. Searches seats.aero across all programs, groups by date, and shows a calendar grid of the best deals. Use when dates are flexible and you want to find the sweet spot. |
| category | orchestration |
| summary | Cheapest award dates for a route across a date range. Calendar grid view. |
| api_key | Seats.aero Pro |
Award Calendar
"When should I fly SFO to NRT on points?" answered with a calendar view.
Searches seats.aero across a date range and presents a grid showing the cheapest award per day, per cabin. Highlights the best dates to fly.
This is an orchestration skill. It tells the agent how to query seats.aero and format the results. No standalone script.
When to Use
- "When's the cheapest time to fly SFO to NRT in business on points?"
- "Show me award availability for SFO-CDG in September"
- "I'm flexible on dates. When should I fly?"
- Any award search where dates are flexible
When NOT to Use
- Specific date search (use
seats-aero directly)
- Cash price calendar (use Google Flights "Date grid" or Skiplagged)
- Hotel date flexibility (not supported here)
Workflow
Step 1: Search the Date Range
Use the seats.aero cached search API with a date range. The API supports up to ~60 days per query.
curl -s -H "Partner-Authorization: $SEATS_AERO_API_KEY" \
"https://seats.aero/partnerapi/search?origin_airport={ORIGIN}&destination_airport={DEST}&start_date={START}&end_date={END}&cabin={CABIN}"
Parameters:
origin_airport: Can be comma-delimited for nearby airports (e.g., SFO,SJC,OAK)destination_airport: Same. Use multiple for metro areas (e.g., NRT,HND for Tokyo)start_date, end_date: YYYY-MM-DD. Keep range under 60 days for best results.cabin: Optional filter. economy, premium, business, first. Omit for all cabins.order_by: Use lowest_mileage to get cheapest first.take: Set to 1000 to get all results in one page.
For ranges over 60 days, split into two queries and combine results.
Step 2: Group by Date
Process the API response:
For each availability object:
date = result.Date
cabin = which cabin(s) are available (Y/W/J/F)
For each available cabin:
cost = result.{cabin}MileageCost
program = result.Source
Track: cheapest cost per date per cabin across all programs
Step 3: Apply Transfer Partner Optimization
For each cheapest-per-date result, calculate the effective cost in transferable currencies using data/transfer-partners.json:
For date 2026-09-05, cheapest business = 55,000 via Flying Blue:
Chase UR: 55,000 / 1.0 = 55,000 UR
Amex MR: 55,000 / 1.0 = 55,000 MR
Bilt: 55,000 / 1.0 = 55,000 Bilt
Step 4: Present Calendar Grid
Always use markdown tables. One table per cabin class requested.
Business Class: SFO → NRT, September 2026
| Date | Program | Miles | Best Currency | Points | CPP* | Seats | Direct |
|---|
| Sep 3 ⭐ | Virgin Atlantic | 52,500 | Chase UR | 52,500 | 8.0 | 2 | ✅ ANA |
| Sep 5 | Flying Blue | 55,000 | Any 1:1 | 55,000 | 7.6 | 4 | ✅ AF |
| Sep 7 | Aeroplan | 70,000 | Chase UR | 70,000 | 6.0 | 1 | ✅ ANA |
| Sep 8 | United | 88,000 | Chase UR | 88,000 | 4.8 | 3 | ✅ UA |
| Sep 10 | — | — | — | — | — | — | ❌ No availability |
| Sep 12 | Aeroplan | 75,000 | Amex MR | 75,000 | 5.6 | 2 | ❌ 1-stop |
| ... | ... | ... | ... | ... | ... | ... | ... |
*CPP calculated against cheapest cash fare from Duffel/Ignav if available, otherwise estimated.
⭐ = Best deal of the month
Summary:
- Best date: Sep 3 via Virgin Atlantic → ANA at 52,500 miles (8.0 cpp)
- Runner-up: Sep 5 via Flying Blue at 55,000 miles
- Worst week: Sep 10-14 (no business availability most days)
- Cheapest economy: Sep 12 at 25,000 United miles
Step 5: Additional Context
After the grid, include:
- Freshness warning: "Data from seats.aero cached search. Last seen times vary. Verify before transferring points."
- Transfer advice: "Don't transfer until you've confirmed the specific flight exists on the airline's website."
- Cash comparison: If a cash price was fetched (from Duffel/Ignav), show the CPP for context.
- Booking links: For the top 3 dates, mention how to book (e.g., "Book via Virgin Atlantic website, call to hold").
- Release date note: If searching far out, mention which airlines may not have released space yet (use seats.aero release date tool).
Error Handling
NEVER fail silently.
- ❌ Seats.aero: API error (rate limit). Try again in a few minutes.
- ⚠️ Seats.aero: Only 12 results for 30-day range. Some dates may have uncached availability. Try live search for specific dates of interest.
- ℹ️ No business availability found for any date. Showing economy and premium economy instead.
If zero results come back for the entire range, say so explicitly and suggest:
- Widening the airport search (add nearby airports)
- Checking a different month
- Looking at different cabins
- Using the seats.aero live search for specific dates (local Patchright only)
Limitations
- Cached data only. Results may be 1-48 hours old. Live search (via seats-aero-web) is more current but Bobby-local only.
- 60-day query limit. Split longer ranges into multiple queries.
- No round-trip optimization. Shows one-way availability. For round-trip, run two calendar searches (outbound and return).
- No cash price calendar. This is award-only. For cash date flexibility, use Google Flights "Date grid" view.
- Phantom availability. Some results may not actually be bookable. Always verify.
