Skip to content
agent-data

Create Flight Search

POST
/api/v1/flight-searches
 
agent-data call bd63936c-8611-45a8-8ad8-083aa4c51aa9 search-flights --date <date> [--sort <sort>] [--cabin <cabin>] [--limit <limit>] [--compact <compact>] [--max_stops <max_stops>] [--passengers <passengers>] [--request_id <request_id>] --origin_iata <origin_iata> [--return_date <return_date>] --destination_iata <destination_iata>

Start a flight search. This endpoint returns immediately with a job_id and status “pending”. The search runs in the background and typically finishes in 6-20 seconds. A 202 response means the search was accepted, not that results are ready. Check on the search by calling GET /api/v1/flight-searches/{job_id} every 2-5 seconds. While status is “pending” or “running”, keep checking. When status is “completed”, the offers are in data.result.offers. When status is “failed”, read error_code and error_message; if retryable is true, submitting the same search again may succeed. Errors always appear on the job you poll, never in this response. Sending the same request_id with the same search body returns the existing job instead of creating a new one. Sending the same request_id with a different body returns 409 idempotency_key_conflict.

Request Body required

Section titled “Request Body required ”
Media type application/json
FlightSearchRequest
object
date
required
Date

Specify the outbound travel date to search. Send an ISO 8601 calendar date in YYYY-MM-DD format. This value is required. Every submission without a request_id runs a fresh upstream search; results are not shared across requests.

string format: date
sort
SortOption

Choose how the API should order offers in the returned result set. Send one of the supported enum values: price, duration, departure, or stops.

string
default: price
Allowed values: price duration departure stops
cabin
CabinClass

Choose the cabin class to request for the priced itinerary. Send one of the documented enum values, such as economy, premium_economy, business, or first.

string
default: economy
Allowed values: economy premium_economy business first
limit
Limit

Cap how many priced offers the API should return in the completed search result. Send an integer from 1 through 30. Values outside that range fail validation with 422.

integer
default: 10 >= 1 <= 30
compact
Compact

Set this flag to request the compact response mode supported by the search workflow. Send a boolean value. The request model accepts the flag today, but downstream response shaping should be described conservatively unless separate evidence confirms a material payload difference.

boolean
max_stops
Any of:
integer
<= 3
passengers
Passengers

Specify how many passengers to price in the search request. Send an integer from 1 through 9. Values outside that range fail validation with 422.

integer
default: 1 >= 1 <= 9
request_id
Any of:
string
>= 8 characters <= 128 characters
origin_iata
required
Origin Iata

Specify the 3-letter IATA code for the departure airport. Input is case-insensitive in practice and is normalized before the upstream search request is built. Send an airport code, not a city code or free-text location.

string
>= 3 characters <= 3 characters
return_date
Any of:
string format: date
destination_iata
required
Destination Iata

Specify the 3-letter IATA code for the arrival airport. Input is case-insensitive in practice and is normalized before the upstream search request is built. Send an airport code, not a city code or free-text location.

string
>= 3 characters <= 3 characters

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Successful Response

Media type application/json
Envelope[FlightSearchJobResponse]
object
data
required
FlightSearchJobResponse

Public-facing response for POST /flight-searches.

Extends FlightSearchJob with the operation pointer used by long-polling clients (operation_id/operation_url) and explicit trust-failure metadata when the upstream result cannot be served accurately.

object
job_id
required
Job Id
string
status
required
SearchJobStatus
string
Allowed values: pending running completed failed
poll_url
required
Poll Url
string
retryable
Any of:
boolean
error_code
Any of:
string
operation_id
Any of:
string
submitted_at
required
Submitted At
string format: date-time
error_message
Any of:
string
operation_url
Any of:
string
meta
required
ResponseMeta
object
cache
Any of:
CacheMetadata
object
hit
required
Hit
boolean
ttl_seconds
required
Ttl Seconds
integer
resource
required
Resource
string
returned
Any of:
integer
request_id
Request Id
string
sources_used
Sources Used
Array<string>
total_results
Any of:
integer
data_freshness
Any of:
string format: date-time
processing_time_ms
required
Processing Time Ms
integer
warnings
Warnings
Array<object>
WarningItem
object
code
required
Code
string
source
required
Source
string
message
required
Message
string
Example 
{
  "data": {
    "status": "pending"
  }
}

422

Section titled “422 ”

Validation Error

Media type application/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
Example generated
{
  "detail": [
    {
      "ctx": {},
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example"
    }
  ]
}