Insights API

API Endpoint

All Insights API operations use a single GraphQL endpoint:

https://api.travelgate.com

Overview

Travelgate's Insights API lets you query booking reports programmatically.

This document provides the query reference and request/response patterns for the Travelgate Insights API.

Common Use Cases

• Booking Analysis: Retrieve detailed and aggregated booking results.
• Performance Reporting: Analyze booking metrics by client, supplier, market, and destination.
• Trend Monitoring: Track booking volume and revenue trends over time using groupBy dimensions.

When to Use Insights, Stats, Logging, or Their APIs

Use these tools together depending on whether you need booking-level business reporting, operational monitoring, UI-based log analysis, or programmatic integrations.

Need	Recommended Tool	Why
Analyze booking behavior, commercial trends, and business dimensions in the platform UI	Insights (web)	Provides built-in business-oriented reporting views for booking analysis
Build custom booking reports programmatically by client, supplier, market, destination, and time dimensions	Insights API	Returns booking detail and aggregation data optimized for business reporting workflows
Review connection health, booking-flow performance, and error ratios in the platform UI	Stats (web)	Provides the built-in monitoring dashboard for operational analysis
Build custom operational dashboards and query aggregated connectivity metrics programmatically	Stats API	Returns aggregated metrics optimized for integrations and reporting workflows
Review and troubleshoot transaction-level traces in the platform UI	Logging (web)	Provides the built-in transaction-level log viewer for operational troubleshooting
Search, extract traces, and download request/response logs programmatically	Logging API	Returns transaction-level log data for audit and troubleshooting workflows

Authentication

All Insights API calls require JWT (JSON Web Token) authentication. Follow the steps in the Admin API Authentication Guide to obtain your bearer token and include it in all API requests.

Quick Example:

Include your JWT token in the Authorization header:

curl 'https://api.travelgate.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --data-raw '{
    "query": "query BookingsReportExample { insights { bookingsReport(where: { requestMode: BUYER bookingAt: { gte: \\"2026-06-01 00:00:00\\" lte: \\"2026-06-30 23:59:59\\" } } limit: 50) { bookingsAggregation { edges { node { InsightsXBookingAggregationData { bookingAt amount amountEur numBookings } } } } } } }"
  }'

Considerations & Business Rules

Before querying Insights, keep in mind the following interpretation rules:

• Perspective Is Mandatory in Practice: While where is optional at schema level, real reporting scenarios require where.requestMode (BUYER or SELLER) to avoid mixed or ambiguous results.
• Aggregation Depends on Grouping: bookingsAggregation results reflect the selected groupBy dimensions. Changing groupBy changes how metrics are grouped and interpreted.
• Date Filters Drive Report Scope: Use precise absolute ranges in where.bookingAt, where.checkInAt, or where.cancelAt to avoid empty outputs or misleading trend windows.
• Operational Incidents Need Monitoring APIs: Use Insights API for business reporting, and use Logging API or Stats API when troubleshooting technical transaction behavior.

Troubleshooting Empty or Unexpected Results

If your query returns no rows or values that look inconsistent, verify the following in order:

1. Confirm where.requestMode matches the perspective you want to analyze.
2. Validate date ranges (gte / lte) and ensure the selected time window contains real traffic.
3. Recheck filter values such as clientCode_in, supplierCode_in, marketCode_in, and countryCode_in.
4. Temporarily remove groupBy to inspect raw (non-grouped) data, then add dimensions progressively.
5. Review adviseMessage in the response for warnings about invalid combinations or data limitations.

Query Overview

bookingsReport

Retrieve booking detail and aggregation data.

insights {
  bookingsReport(
    where: BookingsReportWhereInput
    orderBy: BookingsReportOrderByInput
    groupBy: [BookingsReportGroupByInput!]
    limit: Int
    relay: RelayInput
  ): InsightsXBookingReport
}

Input Highlights

Required

• No top-level argument is strictly required by the schema.
• If where is provided, where.requestMode is required.

Optional

• where.bookingAt, where.checkInAt, where.cancelAt
• where.reference
• where.ownerCode_in, where.groupCode_in, where.accessCode_in
• where.supplierCode_in, where.clientCode_in
• where.marketCode_in, where.countryCode_in
• where.bookingStatus_in
• orderBy, groupBy, limit, relay

Obtaining Filter Values (Equivalences)

If you need to fetch a dynamic list of valid values to populate your Insights filters, use the following equivalence table to find them via the Admin API:

Important: clientCode_in is not buyer_in

In Insights API, where.clientCode_in expects Client codes, not Buyer organization codes.

• Do not use buyer_in values in clientCode_in.
• To populate clientCode_in, retrieve values with the Admin allClients query and use clientData.code.
• Reference: All Clients

Example source path:

query {
  admin {
    allClients {
      edges {
        node {
          clientData {
            code
          }
        }
      }
    }
  }
}

Insights Filter / GroupBy Field	What it Represents	How to obtain it via Admin API
clientCode / clientCode_in	Client Code	Query allClients and use clientData.code
clientOrganization	Buyer Organization Code	Query your Buyers list to retrieve the orgCode
supplierCode	Supplier Code	Query your Suppliers list to retrieve the code
supplierOrganization	Seller Organization Code	Query your Sellers list to retrieve the orgCode

Enum Reference

ModeType

Value	Description
BUYER	Query from the Buyer's perspective
SELLER	Query from the Seller's perspective

BookingsReportOrderByInput

Value	Description
bookingAt_ASC / bookingAt_DES	Sort by booking date ascending or descending
checkInAt_ASC / checkInAt_DES	Sort by check-in date ascending or descending
cancelAt_ASC / cancelAt_DES	Sort by cancellation date ascending or descending
numBookings_ASC / numBookings_DES	Sort by number of bookings ascending or descending
amountEur_ASC / amountEur_DES	Sort by amount in EUR ascending or descending

BookingsReportGroupByInput

Value	Description
status	Group by booking status
clientCode	Group by client code
clientOrganization	Group by client organization
supplierCode	Group by supplier code
supplierOrganization	Group by supplier organization
currency	Group by currency
bookingAt	Group by booking date
checkInAt	Group by check-in date
cancelAt	Group by cancellation date
originMarket	Group by origin market
destinationCountry	Group by destination country
paxType	Group by passenger type
lengthOfStay	Group by length of stay
bookingWindow	Group by booking window
hotel	Group by hotel

BookStatusType

Value	Description
OK	Booking confirmed successfully
KO	Booking failed
ON_REQUEST	Booking pending confirmation
CANCELLED	Booking cancelled
PENDING_COMMIT	Booking awaiting commit
UNKNOWN	Booking status unknown

Baseline Response Shape

Main response sections:

• bookingsDetails — row-level booking records
• bookingsAggregation — grouped aggregation data
• adviseMessage — operational warnings or errors

Advisory Messages (adviseMessage)

The adviseMessage field provides operational warnings or errors associated with your report request. It may be null when the query executes without warnings.

How to interpret adviseMessage:

• code: Machine-readable identifier for the message.
• description: Human-readable explanation of the warning or issue.
• null value: No advisory messages were returned for that request.

Recommended handling workflow:

1. Check whether adviseMessage is null.
2. If not null, review each returned message before using results for reporting.
3. Validate date range and filter combinations when messages indicate constrained or empty results.
4. Fix input conditions indicated by the message and re-run the query.

Examples

In the following examples, you can see how to extract bookings data using the interactive playground.

Example 1: Bookings Report (bookingsReport)

Query:

query BookingsReportExample {
  insights {
    bookingsReport(
      where: {
        requestMode: BUYER
        bookingAt: {
          gte: "2026-06-01 00:00:00"
          lte: "2026-06-30 23:59:59"
        }
        clientCode_in: ["client_demo"]
        supplierCode_in: ["SUPPLIER_CODE"]
        marketCode_in: ["ES"]
        countryCode_in: ["PT"]
        bookingStatus_in: [OK, CANCELLED]
      }
      orderBy: amountEur_DES
      groupBy: [clientCode, supplierCode, bookingAt]
      limit: 50
    ) {
      bookingsDetails {
        edges {
          node {
            InsightsXBookingDetailData {
              reference {
                client
                supplier
                hotel
              }
              hotel {
                bookingDate
                start
                end
                hotelCode
                hotelName
              }
              status
              price {
                net
                gross
                exchange {
                  currency
                  rate
                }
              }
            }
          }
        }
      }
      bookingsAggregation {
        edges {
          node {
            InsightsXBookingAggregationData {
              bookingAt
              amount
              amountEur
              numBookings
            }
          }
        }
      }
    }
  }
}

Sample Response:

{
  "data": {
    "insights": {
      "bookingsReport": {
        "bookingsDetails": {
          "edges": [
            {
              "node": {
                "InsightsXBookingDetailData": {
                  "reference": {
                    "client": "CLI-REF-001",
                    "supplier": "SUP-REF-777",
                    "hotel": "HOTEL-REF-99"
                  },
                  "hotel": {
                    "bookingDate": "2026-06-10",
                    "start": "2026-07-01",
                    "end": "2026-07-05",
                    "hotelCode": "HTL123",
                    "hotelName": "Demo Hotel"
                  },
                  "status": "OK",
                  "price": {
                    "net": 120.5,
                    "gross": 130.0,
                    "exchange": {
                      "currency": "EUR",
                      "rate": 1.0
                    }
                  }
                }
              }
            }
          ]
        },
        "bookingsAggregation": {
          "edges": [
            {
              "node": {
                "InsightsXBookingAggregationData": {
                  "bookingAt": "2026-06-10",
                  "amount": 120.5,
                  "amountEur": 120.5,
                  "numBookings": 1
                }
              }
            }
          ]
        }
      }
    }
  }
}

Variables:

{
  "where": {
    "requestMode": "BUYER",
    "bookingAt": {
      "gte": "2026-06-01 00:00:00",
      "lte": "2026-06-30 23:59:59"
    },
    "clientCode_in": [
      "YOUR_CLIENT_CODE"
    ],
    "bookingStatus_in": [
      "OK",
      "CANCELLED"
    ]
  },
  "orderBy": "amountEur_DES",
  "groupBy": [
    "clientCode",
    "supplierCode",
    "bookingAt"
  ],
  "limit": 50
}

curl Example:

curl 'https://api.travelgate.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --data-raw '{
    "query": "query BookingsReportExample($where: BookingsReportWhereInput, $orderBy: BookingsReportOrderByInput, $groupBy: [BookingsReportGroupByInput!], $limit: Int) { insights { bookingsReport(where: $where, orderBy: $orderBy, groupBy: $groupBy, limit: $limit) { bookingsDetails { edges { node { InsightsXBookingDetailData { reference { client supplier hotel } hotel { bookingDate start end hotelCode hotelName } status price { net gross exchange { currency rate } } } } } } bookingsAggregation { edges { node { InsightsXBookingAggregationData { bookingAt amount amountEur numBookings } } } } adviseMessage { code description } } } }",
    "variables": {
      "where": {
        "requestMode": "BUYER",
        "bookingAt": {
          "gte": "2026-06-01 00:00:00",
          "lte": "2026-06-30 23:59:59"
        },
        "clientCode_in": [
          ""
        ],
        "bookingStatus_in": [
          "OK",
          "CANCELLED"
        ]
      },
      "orderBy": "amountEur_DES",
      "groupBy": [
        "clientCode",
        "supplierCode",
        "bookingAt"
      ],
      "limit": 50
    }
  }'

 

Related Guides

• Stats API
• Logging API