---
title: "Read a flight AI search task"
method: GET
path: "/v1/flight_ai_search/tasks/{task_id}"
tags: ["Discovery"]
---

# Read a flight AI search task

`GET /v1/flight_ai_search/tasks/{task_id}`

## Request

- Base URL: `https://api.gojinko.com`
- URL: `https://api.gojinko.com/v1/flight_ai_search/tasks/{task_id}`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

The task's answer now: `working` with the early reply, or the final answer.

## Path parameters

- `task_id` string, required

## Response `200`

The task.

- FlightAiSearchAnswer
  - `context_id` string, nullable, required: The conversation; send it with the next message to continue.
  - `task_id` string, required
  - `status` 'working' | 'input_required' | 'completed' | 'failed' | 'canceled', required: `working`: the search is still running, read the task again. `input_required`: the message asks a question; answer it in the same conversation. `completed`: the options are in the answer. `failed`: see `error`. `canceled`: a later message or a cancel replaced it.
  - `message` string: The reply to show the traveller, in English.
  - `question` 'origin' | 'which_place' | 'dates' | 'passengers' | 'group_too_large' | 'contradiction' | 'out_of_scope': What the reply asks for, when `status` is `input_required`.
  - `question_options` object[]: Choices for the question, when it has some.
    - `value` string, required: What to send back as `text`.
    - `label` string, required
    - `detail` string
  - `criteria` object: The search the request was understood as: `trip_type`, `origins`, `destinations`, `departure`, `return`, `passengers`, `priority` (only when the request says how to rank the options), `currency`, and the filters, in the `flight_search` field names. Each place of `origins` and `destinations` has `code`, `type`, `name` and `country_code`; `code` is null for a country, a region or a kind of trip, whose airports searched are on each option's `legs`.
  - `notes` object[]: Assumptions and adjustments made while understanding the request and searching, each with a `kind` and the fields of that kind, and an optional `text`.
    - `kind` string, required
  - `options` FlightAiSearchOption[]: Every itinerary of the answer, each priced live.
    - `option_id` string, required: Identifies the option within the answer; `groups` name options by it.
    - `trip_type` 'oneway' | 'roundtrip' | 'multi_city', required
    - `legs` FlightAiSearchLeg[], required: 1 for one way, 2 for a round trip, 2 to 4 for a multi-city trip.
      - `index` integer, required: The leg number, from 1.
      - `origin` object, required
        - `code` string, required: IATA city or airport code.
        - `name` string, required
        - `airport` string: IATA airport code.
      - `destination` object, required
        - `code` string, required: IATA city or airport code.
        - `name` string, required
        - `airport` string: IATA airport code.
      - `departure` string, required: Local time at the origin.
      - `arrival` string: Local time at the destination.
      - `duration_minutes` integer
      - `stops` integer
      - `segments` FlightAiSearchSegment[]: The flights of the leg.
        - `marketing_carrier` string, required: IATA code of the marketing airline.
        - `operating_carrier` string: IATA code of the operating airline, when it differs.
        - `flight_number` string, required
        - `origin` string, required: IATA airport code.
        - `destination` string, required: IATA airport code.
        - `departure` string, required: Local time at `origin`.
        - `arrival` string, required: Local time at `destination`.
        - `duration_minutes` integer, required
        - `layover_minutes` integer: The connection time before the next segment; absent on the last one.
    - `fares` FlightAiSearchFare[]: The bookable fares.
      - `trip_item_token` string, required: Add this fare to a trip with `POST /v1/trip` `add_item`, before `expires_at`. After that the token is refused; use the token of a newer answer. "Show me more" in the same conversation searches expired options again.
      - `brand_name` string, required
      - `cabin_class` string, required
      - `total` object, required: The price for every traveller.
        - `amount` number, required: The amount in major units of `currency` (e.g. 3412.5 for EUR 3,412.50).
        - `currency` string, required: ISO 4217 currency code.
      - `price_per_person` object, required: The price for one traveller.
        - `amount` number, required: The amount in major units of `currency` (e.g. 3412.5 for EUR 3,412.50).
        - `currency` string, required: ISO 4217 currency code.
      - `priced_for` object, required: The travellers `total` is for.
        - `adults` integer, required
        - `children` integer, required
        - `infants` integer, required
      - `expires_at` string, date-time, required: Until when `trip_item_token` can be added to a trip (UTC): at most 75 minutes after the search, earlier when the fare's own deadline is.
      - `refundable` boolean, required
      - `changeable` boolean, required
      - `checked_bag_included` boolean, required
      - `carry_on_baggage` string
      - `included_baggage` string: The checked baggage included.
    - `score` integer: How well the option fits the request, 0–100, relative to this answer.
    - `why` string: One sentence on why the option is shown.
  - `groups` FlightAiSearchGroup[]
    - union: How to present the options; groups name them by `option_id`. `shortlist`: the options for one route and dates. `per_destination`: one row per destination compared. Options always meet every filter of the request; a row without one says why in `empty_reason`.
      - object
        - `kind` 'shortlist', required
        - `group_id` string, required
        - `title` string, required
        - `route` object, nullable, required: Null for a multi-city trip.
          - `origin` string, required
          - `destination` string, required
        - `dates` object, nullable, required: Null when the options differ in dates.
          - `departure` string, required
          - `return` string
        - `option_ids` string[], required: The options, best first.
      - object
        - `kind` 'per_destination', required
        - `group_id` string, required
        - `title` string, required
        - `origin` FlightAiSearchPlace, required: A place the request was understood to name.
          - `code` string, required: IATA city, airport or country code. For a region or a kind of trip, the first airport searched for it.
          - `type` 'city' | 'airport' | 'country' | 'region' | 'theme', required: region: an area of several countries or a part of one ("the Caribbean", "Puglia"). theme: a kind of trip named instead of a place ("skiing at Christmas"), searched at the destinations that fit it; `name` says which ("ski destinations").
          - `name` string, required
          - `country_code` string, nullable, required: ISO 3166-1 alpha-2; null for a place in more than one country (a region such as the Caribbean, a kind of trip).
          - `alternates` string[]: Other airports searched for this place.
        - `rows` object[], required
          - `destination` FlightAiSearchPlace, required: A place the request was understood to name.
            - `code` string, required: IATA city, airport or country code. For a region or a kind of trip, the first airport searched for it.
            - `type` 'city' | 'airport' | 'country' | 'region' | 'theme', required: region: an area of several countries or a part of one ("the Caribbean", "Puglia"). theme: a kind of trip named instead of a place ("skiing at Christmas"), searched at the destinations that fit it; `name` says which ("ski destinations").
            - `name` string, required
            - `country_code` string, nullable, required: ISO 3166-1 alpha-2; null for a place in more than one country (a region such as the Caribbean, a kind of trip).
            - `alternates` string[]: Other airports searched for this place.
          - `dates` object, nullable, required
            - `departure` string, required
            - `return` string
          - `option_id` string, nullable, required: The best live option for this destination; null when there is none.
          - `live_cheapest_total` object, nullable, required: An amount of money and its currency.
            - `amount` number, required: The amount in major units of `currency` (e.g. 3412.5 for EUR 3,412.50).
            - `currency` string, required: ISO 4217 currency code.
          - `empty_reason` 'no_fare_within_filters' | 'not_searched' | 'no_cached_fares': Why `option_id` is null.
          - `summary` string, required
  - `has_more` boolean: More options are available; ask for more in the same conversation.
  - `error` object: Why the task failed, when `status` is `failed`.
    - `code` string, required
    - `message` string, required
  - `superseded_by` string: The task that replaced this one, when `status` is `canceled`.
  - `charge` FlightAiSearchCharge: What a turn was charged to the organization's balance, once the turn has ended (`completed`, `input_required`, `failed` or `canceled`); every amount is 0 when the turn cost nothing. Absent while the task is `working`. Carried on JSON answers only: an event stream does not carry it, so read it with `GET /v1/flight_ai_search/tasks/{task_id}`.
    - `turn` integer, required: The turn of the task this charge is for, from 1; a task answering a question is a later turn.
    - `llm_usd` number, required: The language-model part of the charge, in USD.
    - `api_usd` number, required: The flight search part of the charge, in USD.
    - `total_usd` number, required: `llm_usd` + `api_usd`.
    - `currency` 'USD', required

## Other responses

- `400`: Bad request: an invalid header, such as a reserved `X-End-User-Id` (`user_…`, `org_…`).
- `401`: Authentication required
- `403`: The key is valid but is not a tenant API key (`jnk_t_…`), is not granted the `search_live` scope, or Travel AI search is not enabled for this account. **`FORBIDDEN`** — The credential is valid, and this request is refused anyway. Do not rotate the key — it is working. Check that it is entitled to this operation, and on this environment.
- `404`: Resource not found
- `422`: Validation error
- `429`: Rate limit or quota exceeded
- `502`: The travel provider rejected the request, or an upstream call failed
- `503`: No travel provider can serve the request right now
- `504`: The travel provider did not answer in time

---

[API](https://skmtc.dev/gojinko/apis/jinko-public-api.md) - [All operations](https://skmtc.dev/gojinko/apis/jinko-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gojinko/apis/jinko-public-api/revisions/ac5046767e4c?raw)