> ## Documentation Index
> Fetch the complete documentation index at: https://farelint.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# On-demand searches

> Create a collection job for an exact travel request.

Pre-release endpoint contract. No executable API host is published yet.

## Create a search

`POST /v1/searches`

| Field | Type | Meaning |
| - | - | - |
| carriers | string\[] | Enabled source-airline codes |
| origin / destination | string | IATA airport codes |
| departure\_date | string | Local departure date, YYYY-MM-DD |
| return\_date | string or null | Exact return date, or null for one way |
| passengers | object | Adults, child ages and infants |
| cabin | string | Requested cabin |
| market | string | Point-of-sale country |
| currency | string | Requested ISO currency; returned currency is explicit |
| freshness | string | `fresh_collection` requests a new source collection |
| max\_credits | integer | Upper budget bound; reject before dispatch if the estimate exceeds it |

### Accepted response

```json theme={null}
{
  "example": true,
  "id": "example_search",
  "status": "queued",
  "estimated_credits": 1,
  "credits_charged": 0
}
```

## Retrieve results

`GET /v1/searches/{id}`

The planned job states are `queued`, `running`, `completed`, `partial` and `failed`. Each source carries its own status. The results distinguish a successfully observed empty search from a collection failure.

```json theme={null}
{
  "example": true,
  "id": "example_search",
  "status": "completed",
  "source_results": [{
    "carrier": "FR",
    "status": "completed",
    "observed_at": "2026-10-29T10:42:00Z",
    "source_priced_at": null,
    "observations": [{
      "price": { "amount": "89.90", "currency": "EUR", "basis": "journey_total", "taxes_included": null },
      "baggage": { "checked": null },
      "booking_verified": false
    }],
    "credits_charged": 1
  }]
}
```

This is a shortened schema example, not a real offer. Production observations must retain the original search identity and available itinerary/source details.

## Retry safely

Reuse the same idempotency key for retries of the same body. The proposed behavior returns the original job without another charge. Changed criteria require a new key; conflicting reuse returns an error. Polling does not initiate another collection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.