> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Get an air search grouped by airline and price > Returns the results of an air search grouped into cards by airline and price. Built for a price-first list: a card gathers the flights that share the same airline, the same cheapest fare and the same return options, and lists each distinct outbound and return journey once instead of repeating it for every combination. The traveler picks the airline and fare first and then only picks times. Every outbound of a card combines with every return of it, and two cards can share an airline and a price while offering different times. To get the search item of a chosen combination, read the card's `searchItems`, or intersect the `searchItemIds` of the two journeys chosen. Create a trip with that item's `id` as `searchItemId` and the card's cheapest fare `id` as `fareId`, or open the item for its other fares. It works on air searches only and takes the same pagination, sort and air filters as the search results — `order`, `orderBy`, `limit`, `next`, `minAmount`, `maxAmount`, `airline`, `airlineCode` and `cabin` — except that `next` and `totalCount` count cards, not items. A filter that takes several values accepts them repeated (`?airline=LA&airline=G3`) or comma-separated (`?airline=LA,G3`). While `status` is `PROCESSING` only the search itself comes back: poll until it is `COMPLETED`. Amounts are integers in cents: `98700` is R\$ 987,00. An error the travel provider reports about the request — a filter value it does not accept, say — is returned with its own status, `code` and `message`. ## OpenAPI ````yaml /api-reference/travel.openapi.json get /realms/{realmId}/organizations/{organizationId}/air/searches/{searchId}/aggregate openapi: 3.0.3 info: title: Travel version: 1.0.0 description: >- Portão 3 travel API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Passenger directory, trips and the search proxy (air/hotel/bus/vehicle). Every route validates path, query and body through a zod Input class (`travel/src/domain/*/input`), which documents its parameters and body; responses are the named interfaces in `travel/src/domain/*/response.ts`. Confidence tiers: generated:typed=53 copied:manual=0 unknown=0. servers: - url: https://api.travel.v2.portao3.com.br/ description: production - url: https://api.travel.dev.3pers.com.br/ description: development security: [] tags: - name: Passengers - name: Trips - name: Air search - name: Hotel search - name: Bus search - name: Vehicle search paths: /realms/{realmId}/organizations/{organizationId}/air/searches/{searchId}/aggregate: get: tags: - Air search summary: Get an air search grouped by airline and price description: >- Returns the results of an air search grouped into cards by airline and price. operationId: >- getRealmsByRealmIdOrganizationsByOrganizationIdAirSearchesBySearchIdAggregate parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of your organization. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: searchId in: path required: true description: ID of the air search, as returned when it was created. schema: type: string pattern: ^srch_[0-9A-Za-z]{21}$ example: srch_V1StGXR8Z5jdHi6BmyT2k - name: order in: query required: false description: >- Sort direction applied to `orderBy`: `ASC` lists the cheapest cards first, `DESC` the most expensive first. schema: type: string enum: - ASC - DESC example: ASC - name: orderBy in: query required: false description: Field to sort the cards by. Currently only `amount` is supported. schema: type: string minLength: 1 example: amount - name: next in: query required: false description: >- Cursor returned as `next` by the previous page. Omit for the first page. schema: type: string minLength: 1 example: eyJwIjoyfQ== - name: limit in: query required: false description: Maximum number of cards per page, from 1 to 100. schema: type: integer minimum: 1 maximum: 100 example: 20 - name: minAmount in: query required: false description: >- Only cards costing at least this amount, in the same unit as the `amount` of the fares (cents). schema: type: number minimum: 0 example: 20000 - name: maxAmount in: query required: false description: >- Only cards costing at most this amount, in the same unit as the `amount` of the fares (cents). schema: type: number minimum: 0 example: 100000 - name: airline in: query required: false description: |- Only flights sold by these airlines, by name (case-insensitive). --- Example (comma-separated list): `?airline=LATAM,Gol` schema: type: array items: type: string style: form explode: false - name: airlineCode in: query required: false description: >- Only flights sold by these airlines, by IATA code (case-insensitive). --- Example (comma-separated list): `?airlineCode=LA,G3` schema: type: array items: type: string style: form explode: false - name: cabin in: query required: false description: >- Only flights with a fare in these cabins: `ECONOMY`, `PREMIUM_ECONOMY`, `BUSINESS`, `FIRST_CLASS` or `UNDEFINED`. A flight is kept when at least one of its fares has a segment in one of them. --- Example (comma-separated list): `?cabin=ECONOMY,BUSINESS` schema: type: array items: type: string style: form explode: false responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: ID of the search. example: srch_V1StGXR8Z5jdHi6BmyT2k searchParams: type: object properties: departureDate: type: string description: Outbound date, as sent. example: '2026-11-02' returnDate: type: string description: Return date, as sent. Absent for a one-way trip. example: '2026-11-05' origin: type: string description: Origin airport, as sent. example: GRU destination: type: string description: Destination airport, as sent. example: GIG passengers: type: array items: type: string enum: - ADULT - CHILD - INFANT - SENIOR example: ADULT description: |- Travelers, as sent. --- Example: `["ADULT"]` cabin: type: string enum: - ECONOMY - PREMIUM_ECONOMY - BUSINESS - FIRST_CLASS - UNDEFINED description: Cabin searched; `ECONOMY` when the request had none. example: ECONOMY required: - departureDate - origin - destination - passengers - cabin description: What the search was made for. type: type: string enum: - AIR description: Always `AIR`. example: AIR status: type: string enum: - PROCESSING - FAILED - COMPLETED description: >- `PROCESSING`, `COMPLETED` or `FAILED`. Only `COMPLETED` carries cards. example: COMPLETED warning: description: >- How the search went across the suppliers. `null` while it is processing. type: object properties: code: type: string enum: - ALL_FAILED - PARTIAL_SUCCESS - ALL_SUCCESS description: >- `ALL_SUCCESS`: every supplier answered. `PARTIAL_SUCCESS`: some suppliers failed, so the results may be incomplete. `ALL_FAILED`: no supplier answered. example: ALL_SUCCESS message: type: string description: Human-readable explanation. example: All suppliers answered. required: - code - message nullable: true ttl: type: number description: Seconds until the search expires. example: 640 facets: description: >- Facets to build filters from (price ranges, airlines). `null` until the search completes. type: object additionalProperties: {} nullable: true createdAt: type: string description: When the search was created. example: '2026-10-19T15:00:00.000Z' format: date-time items: type: array items: type: object properties: airline: type: object properties: code: type: string description: IATA code of the airline. example: LA name: type: string nullable: true description: Commercial name. `null` when unknown. example: LATAM Airlines logo: type: string nullable: true description: URL of the airline's logo. `null` when unknown. example: https://example.com/logos/la.svg required: - code - name - logo description: Airline shared by every combination of the card. occupants: type: number description: Number of travelers the search was made for. example: 1 cheapestFare: description: >- Cheapest fare shared by the card. `null` when its items have no fare. type: object properties: id: type: string description: >- ID of the fare. Send it as `fareId` when you create a trip with one of the card's items. example: fare_Jh2Xv8NcQd5Wp1RkTy7Ab description: type: string description: Name of the fare. example: LIGHT fare: type: object properties: currency: type: string description: Currency of the amounts (ISO 4217). example: BRL originalAmount: type: number description: Price before discounts and fees, in cents. example: 105000 discountAmount: type: number description: >- Discount applied to the original amount, in cents. example: 10000 feeAmount: type: number description: Fees added to the fare, in cents. example: 3700 amount: type: number description: >- Total charged: `originalAmount - discountAmount + feeAmount`, in cents (`98700` is R$ 987,00). example: 98700 cancellationPolicies: type: object properties: refundable: type: boolean description: >- Whether the fare allows any refund at all. example: true immediateFine: type: boolean description: >- Whether a fine is charged for cancelling right after booking. example: false penalties: type: array items: type: object properties: from: type: string description: >- Date (`YYYY-MM-DD`) from which this tier applies. example: '2026-10-30' currency: type: string description: Currency of the penalty (ISO 4217). example: BRL fineAmount: type: number description: >- Penalty charged when cancelling or changing from `from` onward, in cents. example: 15000 required: - from - currency - fineAmount description: >- One tier of a cancellation or change penalty schedule. description: >- Penalty schedule, in effect from each tier's date. Empty or omitted when no scheduled penalty applies. required: - refundable - immediateFine description: >- Cancellation rules of the fare. Only in the item detail, not in the search results. changePolicies: type: object properties: canChange: type: boolean description: >- Whether the fare allows the booking to be changed. example: true immediateFine: type: boolean description: >- Whether a fine is charged for changing right after booking. example: false penalties: type: array items: type: object properties: from: type: string description: >- Date (`YYYY-MM-DD`) from which this tier applies. example: '2026-10-30' currency: type: string description: Currency of the penalty (ISO 4217). example: BRL fineAmount: type: number description: >- Penalty charged when cancelling or changing from `from` onward, in cents. example: 15000 required: - from - currency - fineAmount description: >- One tier of a cancellation or change penalty schedule. description: >- Penalty schedule, in effect from each tier's date. Empty when none applies. required: - canChange - immediateFine - penalties description: >- Change rules of the fare. Only in the item detail, not in the search results. required: - currency - originalAmount - discountAmount - feeAmount - amount description: Price of the fare. required: - id - description - fare nullable: true journeys: type: array items: type: object properties: direction: type: string enum: - DEPARTURE - RETURN description: >- `DEPARTURE` for outbound options, `RETURN` for the way back. example: DEPARTURE options: type: array items: type: object properties: id: type: string description: >- ID of the journey; the same journey has the same ID in every item. example: jour_Ac9Ld4MsTe6Vn1WqXr8Hu searchItemIds: type: array items: type: string example: srch_item_V1StGXR8Z5jdHi6BmyT2k description: >- IDs of the search items this journey appears in. The items that contain both an outbound and a return option are the ones that pair them. --- Example: `["srch_item_V1StGXR8Z5jdHi6BmyT2k"]` origin: type: object properties: id: type: string description: ID of the airport. example: airpt_Kd3Hq9RwTz5Lx2NvBm8Ys iata: type: string description: IATA code, 3 letters. example: GRU slug: type: string description: >- Readable unique identifier of the airport. example: sao-paulo-guarulhos-international name: type: string description: Official name of the airport. example: >- São Paulo/Guarulhos International Airport shortAddress: type: string nullable: true description: >- The address in a single line. `null` when unknown. example: Guarulhos, SP, Brazil locality: type: string nullable: true description: City. `null` when unknown. example: Guarulhos administrativeArea: type: string nullable: true description: >- State or province code. `null` when unknown. example: SP phoneNumbers: type: array items: type: string example: '+551133334444' description: >- Contact phone numbers. Empty when none is registered. --- Example: `["+551133334444"]` coordinates: description: >- Position of the airport. `null` when unknown. type: object properties: lat: type: number description: Latitude, in decimal degrees. example: -23.4356 lng: type: number description: Longitude, in decimal degrees. example: -46.4731 required: - lat - lng nullable: true required: - id - iata - slug - name - shortAddress - locality - administrativeArea - phoneNumbers - coordinates description: Departure airport of the journey. destination: type: object properties: id: type: string description: ID of the airport. example: airpt_Kd3Hq9RwTz5Lx2NvBm8Ys iata: type: string description: IATA code, 3 letters. example: GRU slug: type: string description: >- Readable unique identifier of the airport. example: sao-paulo-guarulhos-international name: type: string description: Official name of the airport. example: >- São Paulo/Guarulhos International Airport shortAddress: type: string nullable: true description: >- The address in a single line. `null` when unknown. example: Guarulhos, SP, Brazil locality: type: string nullable: true description: City. `null` when unknown. example: Guarulhos administrativeArea: type: string nullable: true description: >- State or province code. `null` when unknown. example: SP phoneNumbers: type: array items: type: string example: '+551133334444' description: >- Contact phone numbers. Empty when none is registered. --- Example: `["+551133334444"]` coordinates: description: >- Position of the airport. `null` when unknown. type: object properties: lat: type: number description: Latitude, in decimal degrees. example: -23.4356 lng: type: number description: Longitude, in decimal degrees. example: -46.4731 required: - lat - lng nullable: true required: - id - iata - slug - name - shortAddress - locality - administrativeArea - phoneNumbers - coordinates description: Arrival airport of the journey. departureDate: type: string description: >- Departure, in the local time of the departure airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset). example: '2026-11-02T08:30:00' arrivalDate: type: string description: >- Arrival, in the local time of the arrival airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset). example: '2026-11-02T09:35:00' duration: type: string description: >- Total travel time, connections included, `HH:mm`. example: '01:05' segments: type: array items: type: object properties: airline: type: object properties: code: type: string description: IATA code of the airline. example: LA name: type: string nullable: true description: Commercial name. `null` when unknown. example: LATAM Airlines logo: type: string nullable: true description: >- URL of the airline's logo. `null` when unknown. example: https://example.com/logos/la.svg required: - code - name - logo description: Airline that sells the seat. operation: type: object properties: code: type: string description: IATA code of the airline. example: LA name: type: string nullable: true description: Commercial name. `null` when unknown. example: LATAM Airlines logo: type: string nullable: true description: >- URL of the airline's logo. `null` when unknown. example: https://example.com/logos/la.svg required: - code - name - logo description: >- Airline that operates the flight. It differs from `airline` on codeshares. origin: type: object properties: id: type: string description: ID of the airport. example: airpt_Kd3Hq9RwTz5Lx2NvBm8Ys iata: type: string description: IATA code, 3 letters. example: GRU slug: type: string description: >- Readable unique identifier of the airport. example: sao-paulo-guarulhos-international name: type: string description: Official name of the airport. example: >- São Paulo/Guarulhos International Airport shortAddress: type: string nullable: true description: >- The address in a single line. `null` when unknown. example: Guarulhos, SP, Brazil locality: type: string nullable: true description: City. `null` when unknown. example: Guarulhos administrativeArea: type: string nullable: true description: >- State or province code. `null` when unknown. example: SP phoneNumbers: type: array items: type: string example: '+551133334444' description: >- Contact phone numbers. Empty when none is registered. --- Example: `["+551133334444"]` coordinates: description: >- Position of the airport. `null` when unknown. type: object properties: lat: type: number description: Latitude, in decimal degrees. example: -23.4356 lng: type: number description: Longitude, in decimal degrees. example: -46.4731 required: - lat - lng nullable: true required: - id - iata - slug - name - shortAddress - locality - administrativeArea - phoneNumbers - coordinates description: Departure airport. destination: type: object properties: id: type: string description: ID of the airport. example: airpt_Kd3Hq9RwTz5Lx2NvBm8Ys iata: type: string description: IATA code, 3 letters. example: GRU slug: type: string description: >- Readable unique identifier of the airport. example: sao-paulo-guarulhos-international name: type: string description: Official name of the airport. example: >- São Paulo/Guarulhos International Airport shortAddress: type: string nullable: true description: >- The address in a single line. `null` when unknown. example: Guarulhos, SP, Brazil locality: type: string nullable: true description: City. `null` when unknown. example: Guarulhos administrativeArea: type: string nullable: true description: >- State or province code. `null` when unknown. example: SP phoneNumbers: type: array items: type: string example: '+551133334444' description: >- Contact phone numbers. Empty when none is registered. --- Example: `["+551133334444"]` coordinates: description: >- Position of the airport. `null` when unknown. type: object properties: lat: type: number description: Latitude, in decimal degrees. example: -23.4356 lng: type: number description: Longitude, in decimal degrees. example: -46.4731 required: - lat - lng nullable: true required: - id - iata - slug - name - shortAddress - locality - administrativeArea - phoneNumbers - coordinates description: Arrival airport. flightNumber: type: string description: Flight number, without the airline code. example: '3300' departureDate: type: string description: >- Departure, in the local time of the departure airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset). example: '2026-11-02T08:30:00' arrivalDate: type: string description: >- Arrival, in the local time of the arrival airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset). example: '2026-11-02T09:35:00' flightType: type: string enum: - CHARTER - ALLOTMENT - REGULAR description: '`REGULAR`, `CHARTER` or `ALLOTMENT`.' example: REGULAR duration: type: string description: Flight time, `HH:mm`. example: '01:05' equipment: type: string nullable: true description: >- Aircraft scheduled for the flight, as the airline identifies it. `null` when not informed. example: 32Q required: - airline - operation - origin - destination - flightNumber - departureDate - arrivalDate - flightType - duration - equipment description: One flight of a journey. description: The flights of the journey, in order. required: - id - searchItemIds - origin - destination - departureDate - arrivalDate - duration - segments description: One journey option of an air card. description: >- The distinct journeys available in this direction. Each appears once. required: - direction - options description: >- The journey options of an air card in one direction. description: >- The journey options by direction: one group for a one-way search, two (outbound first) for a round trip. searchItems: type: array items: type: object properties: id: type: string description: >- ID of the search item. Send it as `searchItemId` when you create a trip. example: srch_item_V1StGXR8Z5jdHi6BmyT2k journeyIds: type: array items: type: string example: jour_Ac9Ld4MsTe6Vn1WqXr8Hu description: >- IDs of the journeys of the item, in travel order: the outbound first and, for a round trip, the return. --- Example: `["jour_Ac9Ld4MsTe6Vn1WqXr8Hu","jour_Bd3Nf7PtUg2Xk5YrZs9Jw"]` required: - id - journeyIds description: >- A combination a card offers: the search item and the journeys it is made of. description: >- The combinations the card offers, as an item ID with its journeys. required: - airline - occupants - cheapestFare - journeys - searchItems description: >- A card: the items that share the same airline, the same cheapest fare and the same return options, with each distinct journey listed once. Every outbound of a card combines with every return of it. description: >- The cards of this page. Present only once the search is `COMPLETED`. next: type: string nullable: true description: >- Cursor for the next page of cards. `null` on the last page. Present only once the search is `COMPLETED`. example: eyJwIjoyfQ== totalCount: type: number description: >- Number of cards that match the filters, not of items. Present only once the search is `COMPLETED`. example: 1 required: - id - searchParams - type - status - warning - ttl - facets - createdAt description: The results of an air search grouped by airline and price. '404': description: >- `SEARCH_NOT_FOUND` — The search doesn't exist, has expired, was created by another organization or is not an air search. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - SEARCH_NOT_FOUND description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - TRAVEL description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: SEARCH_NOT_FOUND origin: TRAVEL message: Search not found '422': description: >- `BAD_REQUEST` — A path parameter is not a valid ID or a query parameter is invalid; `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - TRAVEL description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: TRAVEL message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: order message: 'Invalid option: expected one of "ASC"|"DESC"' code: ORDER_ONE_OF '503': description: >- `PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - PROVIDER_UNAVAILABLE description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - TRAVEL description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: PROVIDER_UNAVAILABLE origin: TRAVEL message: Travel provider temporarily unavailable, please retry. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.