---
title: "Start a flight search in the background — returns search_id immediately"
method: POST
path: "/flights/search/async"
tags: ["flights"]
---

# Start a flight search in the background — returns search_id immediately

`POST /flights/search/async`

## Request

- Base URL: `https://letsfg.co/developers/api/v1`
- URL: `https://letsfg.co/developers/api/v1/flights/search/async`
- Auth: API key in header `X-API-Key`

Non-blocking version of POST /flights/search. Returns a search_id in under 1 second. Poll GET /flights/results/{search_id} every 5–10 seconds for status and results. Billing is identical to the blocking search — counted as one search on completion, only if it returns offers.

Status values: `pending` (still running), `complete` (offers ready), `error` (search failed).

## Request body

- FlightSearchRequest
  - `origin` string, required: IATA departure code (e.g. LON, JFK)
  - `destination` string, required: IATA arrival code (e.g. BCN, LAX)
  - `date_from` string, date, required
  - `date_to` string, date
  - `return_from` string, date
  - `return_to` string, date
  - `adults` integer
  - `children` integer
  - `infants` integer
  - `cabin_class` 'M' | 'W' | 'C' | 'F'
  - `max_stopovers` integer
  - `currency` string
  - `locale` string
  - `limit` integer
  - `sort` string
  - `departure_time_from` string
  - `departure_time_to` string
  - `provider_filters` object
  - `min_hours_at_destination` integer, nullable: Same-day round trip only (return_from equal to date_from): minimum hours between outbound landing and return departure. Offers with a shorter layover are excluded.
  - `max_return_hour` integer, nullable: Same-day round trip only (return_from equal to date_from): latest local hour the return may land on the calendar day after departure (e.g. 2 = home by 2 AM) before it is filtered out. Defaults to 2 so a real same-day round trip whose return crosses midnight by an hour or two is not silently reported as zero results. Same-day evening landings (before midnight) are always kept regardless of this value. Pass 0 to require a strict same-calendar-day return.

## Response `200`

Search started. Poll the poll_url for results.

- AsyncSearchStartResponse
  - `search_id` string: Pass to GET /flights/results/{search_id} to poll for results.
  - `status` 'pending'
  - `poll_url` string, uri
  - `poll_interval_seconds` integer
  - `note` string

## Other responses

- `402`: Prepaid balance empty or payment method missing.

---

[API](https://skmtc.dev/letsfg/apis/letsfg-public-developer-api.md) · [All operations](https://skmtc.dev/letsfg/apis/letsfg-public-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/letsfg/apis/letsfg-public-developer-api/revisions/516ab6ba1d2e?raw)