Stats API
API Endpoint
All Stats API operations use a single GraphQL endpoint:
https://api.travelgate.com
Overview
Stats is the real-time connectivity performance dashboard of Travelgate. Use the Stats API to programmatically monitor connection performance, check error rates, and analyze booking flow metrics. This API lets you extract and query statistical data by connection, operation type, buyer/seller perspective, and time range for detailed performance insights.
Common Use Cases
- Monitor Connection Error Rates: Track NOK (error) percentages for your connections to identify performance issues.
- Analyze Booking Flow Performance: Measure the performance of Search, Quote, Book, and Cancel operations to understand your conversion funnel.
- Troubleshoot Traffic Issues: Investigate traffic patterns, error types, and transaction volumes in real-time or aggregated views.
- Filter Out Test Traffic: Use
excludeTestSupplierto exclude internal or test supplier traffic from your analysis for accurate performance insights. - Performance Dashboards: Build custom dashboards using aggregated stats grouped by operation type, traffic type, Buyer/Seller, or time periods.
This document details the steps to extract and query metrics using the Travelgate Stats API.
Stats is the currently published Monitoring API.
When to Use Stats, Stats API, or Logging
Use these tools together depending on whether you need dashboard monitoring, programmatic access, or transaction-level troubleshooting.
| Need | Recommended Tool | Why |
|---|---|---|
| Review connection health, booking-flow performance, and NOK ratios in the platform UI | Stats | Provides the built-in monitoring dashboard for operational analysis |
| Build custom dashboards, automate reporting, or query aggregated metrics programmatically | Stats API | Returns aggregated metrics optimized for integrations and reporting workflows |
| Investigate a specific transaction or inspect request/response logs | Logging | Provides transaction-level traceability for troubleshooting |
For transaction-level investigations, see How to Use Logging and How to Audit Supplier Transactions.
Authentication
All Stats API calls require JWT (JSON Web Token) authentication. Follow the steps in the Monitoring 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 getAggregatedStats($where: StatsAggregationConnectionWhereInput!, $groupBy: StatsAggregationConnectionGroupByInput!) { stats { getAggregationStats(where: $where, groupBy: $groupBy) { totalCount edges { node { aggregationData { hits operationType } } } } } }",
"variables": {
"where": {
"mode": "BUYER",
"buyer_in": ["BUYER_CODE"],
"timeRange": {
"absolute": {
"from": "2026-04-14 00:00:00",
"to": "2026-04-14 12:00:00"
}
}
},
"groupBy": {
"data": ["OPERATION_TYPE"]
}
}
}'
Considerations & Business Rules
- "OK" Status vs. Reservation Status: The "OK" data in Stats only indicates that the transaction was technically successful. It does not reflect the actual booking status of a reservation. To know the real status, you must perform a BookingRead operation.
- The "Other" Operation: The
OTHERcategory covers operations outside the standard booking flow. For HotelX, these are equivalent to:- Hotels Query (HotelList, DescriptiveInfo)
- Booking Read and Booking List (ReservationRead, ReservationList)
- Rooms Query and Boards Query (RoomList, MealPlanList)
- Traffic Types: When filtering your Stats, you can use the
trafficType_inparameter:BASIC,SPEED,SCHEDULER, orOPTIMIZED.
Traffic Type Filtering Patterns
Use trafficType_in in where to isolate the traffic source for specific troubleshooting scenarios.
- Diagnose seller-managed traffic by filtering
BASICandOPTIMIZED. - Measure cache behavior by filtering only
SPEED. - Audit static-content update traffic by filtering
SCHEDULER.
For the full meaning of each traffic type in the Stats dashboard, see Traffic Types.
Choosing the Right Query
The Stats API provides two main query types, each suited for different use cases:
When to Use getAggregationStats
Use getAggregationStats for:
- Historical Analysis: Analyze stats from hours, days, or weeks in the past
- Trend Analysis: Compare performance across time periods, operation types, or connections
- SLA Monitoring: Validate service levels over agreed-upon time windows
- Large Time Ranges: Query days or weeks of data grouped by hour or day
Example: "Show me the total search hits and average response time grouped by operation type for the last 7 days"
When to Use getRealTimeRangeStats
Use getRealTimeRangeStats for:
- Real-Time Monitoring: Monitor traffic patterns in live, smaller time windows (minutes to hours)
- Traffic Anomaly Detection: Identify sudden spikes or drops in traffic
- Small Time Windows: Query recent data (last few hours) with minute-level granularity
- Live Dashboards: Build dashboards that update with the latest minute-by-minute metrics
Example: "Show me the hits and errors for the last hour, broken down by minute"
Query Overview
The Stats API offers several methods to retrieve information, depending on the level of detail and grouping you need:
1. getAggregationStats
Primary query used to retrieve grouped statistical data (hits, time, errors) based on specific criteria. It is commonly used to render charts, graphs, and aggregated data tables.
2. getRealTimeRangeStats
Used for real-time monitoring of requests and metrics in updated, smaller time blocks.
A. Where (Filters)
The where input allows you to precisely filter the statistics based on time range, buyers, APIs, or traffic types.
{
"where": {
"mode": "BUYER",
"buyer_in": ["BUYER_CODE"],
"operationType_in": ["SEARCH"],
"timeRange": {
"absolute": {
"from": "2026-04-14 00:00:00",
"to": "2026-04-14 12:00:00"
}
}
}
}
Mandatory criteria:
mode(Search perspective, eitherBUYERorSELLER).timeRange(Absolute date range using the format"YYYY-MM-DD HH:mm:ss").
Optional filters:
excludeTestSupplier(Boolean): Set totrueto exclude test supplier traffic from results. Useful for filtering out noise and focusing on production metrics. Default isfalse.
B. Group By
The groupBy input defines how the returned data will be aggregated.
{
"groupBy": {
"data": ["OPERATION_TYPE"]
}
}
Optional grouping:
data: Fields by which to group the results (e.g.,OPERATION_TYPE,BUYER,SELLER).time: Temporal grouping likeMINUTE,HOUR,DAY,MONTH.
C. Enum Reference
Data Grouping Fields (StatsDataGroupBy)
The data field in groupBy uses the StatsDataGroupBy enum to specify dimensions for aggregation. Use any one or combination of the values listed below to break down your stats:
| Value | Description |
|---|---|
BUYER | Group by the buyer organization |
SELLER | Group by the seller organization |
ACCESS | Group by access (the set of credentials and authentication configuration used by a Buyer to connect to a Seller) |
CLIENT | Group by client (the Buyer-defined tag used to categorize traffic, for example B2B or B2C) |
SUPPLIER | Group by the supplier or seller system |
OPERATION | Group by the operation or API name (for example, hotel) |
OPERATION_TYPE | Group by operation type: SEARCH, QUOTE, BOOKING, CANCEL, OTHER |
TRAFFIC_TYPE | Group by traffic type (BASIC, SPEED, SCHEDULER, OPTIMIZED) |
ERROR_CODE | Group by specific error code |
ERROR_TYPE | Group by error type |
API | Group by API |
This is the complete list of StatsDataGroupBy enum values supported by the Stats API. You can combine multiple values in a single groupBy.data array (for example, ["OPERATION_TYPE", "ERROR_CODE"]) to create multi-dimensional aggregations.
The OPERATION_TYPE field is restricted to SEARCH, QUOTE, BOOKING, CANCEL, and OTHER. Other operation type values exist in the OperationType enum used by other Travelgate APIs (SCHEDULER, CREATE, READ, UPDATE, DELETE, EXECUTE) but are not supported by the Stats API.
Time Grouping Fields
The time field in groupBy allows you to aggregate data by time buckets:
| Value | Description |
|---|---|
MINUTE | Group results into 1-minute buckets |
HOUR | Group results into 1-hour buckets |
DAY | Group results into 1-day buckets |
MONTH | Group results into 1-month buckets |
Mode Values
The mode field specifies whose perspective you want to query:
| Value | Description |
|---|---|
BUYER | Query statistics from the buyer's perspective (incoming requests from buyers) |
SELLER | Query statistics from the seller's perspective (outgoing requests to sellers) |
Operation Type Values
The operationType_in filter in Stats API accepts these operation type values:
| Value | Description |
|---|---|
SEARCH | Search operations - initial hotel availability queries |
QUOTE | Quote operations - rate and availability confirmation |
BOOKING | Booking operations - reservation creation and confirmation |
CANCEL | Cancel operations - reservation cancellations |
OTHER | Other operations - non-booking flow operations like HotelList, DescriptiveInfo, ReservationRead, RoomList, etc. |
The broader OperationType enum used by other Travelgate APIs includes additional values (SCHEDULER, CREATE, READ, UPDATE, DELETE, EXECUTE) that are not supported by the Stats API.
Traffic Type Values
The trafficType_in field filters by traffic source when using Speed or Scheduler solutions:
| Value | Description |
|---|---|
BASIC | Standard direct traffic between buyer and seller without Speed/Scheduler |
SPEED | Traffic routed through the Speed cache solution |
SCHEDULER | Traffic for static content management via the Scheduler solution |
OPTIMIZED | Background update requests sent by Travelgate to update internal databases |
Response Fields
adviseMessage
The adviseMessage field appears in both getAggregationStats and getRealTimeRangeStats responses to provide operational guidance. It may be null if no warnings or issues are detected.
adviseMessage Structure:
[
{
"code": "SAMPLE_CODE",
"type": "SAMPLE_TYPE",
"description": "Description of the advisory message",
"level": "WARN",
"correlationID": "1234567890",
"external": null
}
]
adviseMessage Levels:
| Level | Meaning | Action Required |
|---|---|---|
INFO | Informational message, no action needed | None - informational only |
WARN | Caution recommended, may affect data accuracy | Review the message and consider investigation |
ERROR | Significant issue detected | Immediate investigation recommended |
adviseMessage Fields:
| Field | Type | Description |
|---|---|---|
code | ID! | Message code returned by the API |
type | String! | Message type/category |
description | String! | Human-readable message description |
level | AdviseMessageLevel! | Severity level (WARN, ERROR, INFO) |
correlationID | ID! | Identifier for troubleshooting and support investigations |
external | ExternalMessage | Optional external message payload |
Common adviseMessage Scenarios:
- Incomplete Data: When a query returns partial data or has gaps, adviseMessage indicates the data may not be complete for the requested period.
- Data Lag: When querying very recent time windows, adviseMessage may indicate the data is still being processed and more recent results may appear in the next query.
- Filter Mismatches: When filters don't match any data, adviseMessage explains why no results were returned.
- Query Limits: When results are truncated due to pagination or size limits, adviseMessage provides guidance.
If adviseMessage is not null, examine each message in the list and use level, description, and correlationID to understand potential data limitations and speed up support investigations.
Examples
In the following examples, you can see how to extract different types of stats using the interactive playground.
Example 1: Aggregation Stats (getAggregationStats)
Primary query used to retrieve grouped statistical data based on specific criteria.
Query:
query getAggregatedStats($where: StatsAggregationConnectionWhereInput!, $groupBy: StatsAggregationConnectionGroupByInput!) {
stats {
getAggregationStats(where: $where, groupBy: $groupBy) {
totalCount
adviseMessage {
code
description
level
}
edges {
node {
aggregationData {
hits
time
totalTime
errorType
errorCode
operationType
operation {
code
}
seller {
code
}
buyer {
code
}
access {
code
}
client {
clientData {
code
name
}
}
supplier {
code
}
}
}
}
}
}
}
Variables:
{
"where": {
"mode": "BUYER",
"buyer_in": ["BUYER_CODE"],
"trafficType_in": ["BASIC", "SPEED"],
"api_in": ["hotel"],
"excludeTestSupplier": true,
"timeRange": {
"absolute": {
"from": "2026-04-14 00:00:00",
"to": "2026-04-14 12:00:00"
}
}
},
"groupBy": {
"data": ["OPERATION_TYPE"]
}
}
Sample Response:
{
"data": {
"stats": {
"getAggregationStats": {
"totalCount": 3,
"adviseMessage": null,
"edges": [
{
"node": {
"aggregationData": {
"hits": 1250,
"time": 450,
"totalTime": 562500,
"errorType": "NO_ERROR",
"errorCode": null,
"operationType": "SEARCH",
"operation": {
"code": "hotel"
},
"seller": null,
"buyer": {
"code": "BUYER_CODE"
},
"access": null,
"client": null,
"supplier": null
}
}
},
{
"node": {
"aggregationData": {
"hits": 85,
"time": 320,
"totalTime": 27200,
"errorType": "NO_ERROR",
"errorCode": null,
"operationType": "QUOTE",
"operation": {
"code": "hotel"
},
"seller": null,
"buyer": {
"code": "BUYER_CODE"
},
"access": null,
"client": null,
"supplier": null
}
}
},
{
"node": {
"aggregationData": {
"hits": 42,
"time": 520,
"totalTime": 21840,
"errorType": "NO_ERROR",
"errorCode": null,
"operationType": "BOOKING",
"operation": {
"code": "hotel"
},
"seller": null,
"buyer": {
"code": "BUYER_CODE"
},
"access": null,
"client": null,
"supplier": null
}
}
}
]
}
}
}
}
curl Example:
curl 'https://api.travelgate.com' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data-raw '{
"query": "query getAggregatedStats($where: StatsAggregationConnectionWhereInput!, $groupBy: StatsAggregationConnectionGroupByInput!) { stats { getAggregationStats(where: $where, groupBy: $groupBy) { totalCount adviseMessage { code description level } edges { node { aggregationData { hits time totalTime errorType errorCode operationType operation { code } seller { code } buyer { code } access { code } client { clientData { code name } } supplier { code } } } } } } }",
"variables": {
"where": {
"mode": "BUYER",
"buyer_in": ["BUYER_CODE"],
"trafficType_in": ["BASIC", "SPEED"],
"api_in": ["hotel"],
"excludeTestSupplier": true,
"timeRange": {
"absolute": {
"from": "2026-04-14 00:00:00",
"to": "2026-04-14 12:00:00"
}
}
},
"groupBy": {
"data": ["OPERATION_TYPE"]
}
}
}'
Example 2: Real Time Stats (getRealTimeRangeStats)
Used for real-time monitoring of requests and metrics in small time blocks.
Query:
query getRealTimeStats($where: StatsRealTimeRangeWhereInput!) {
stats {
getRealTimeRangeStats(where: $where) {
realTimeRangeData {
from
to
}
adviseMessage {
code
description
level
}
}
}
}
Variables:
{
"where": {
"timeRange": {
"absolute": {
"from": "2026-04-14 15:00:00",
"to": "2026-04-14 16:00:00"
}
},
"groupByTime": "MINUTE"
}
}
Sample Response:
{
"data": {
"stats": {
"getRealTimeRangeStats": {
"realTimeRangeData": {
"from": "2026-04-14 15:00:00",
"to": "2026-04-14 16:00:00"
},
"adviseMessage": null
}
}
}
}
Response Fields:
- realTimeRangeData.from (
DateTime): The start of the requested time range - realTimeRangeData.to (
DateTime): The end of the requested time range - adviseMessage (
[AdviseMessage]): Optional warnings or information about the query results (see Response Fields section)
getRealTimeRangeStats validates the time range and data availability. To retrieve actual metrics (hits, time, errors) grouped by time buckets, use getAggregationStats with groupBy.time set to MINUTE, HOUR, DAY, or MONTH and include fields like hits, time, totalTime, and errorType in your query.
curl Example:
curl 'https://api.travelgate.com' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data-raw '{
"query": "query getRealTimeStats($where: StatsRealTimeRangeWhereInput!) { stats { getRealTimeRangeStats(where: $where) { realTimeRangeData { from to } adviseMessage { code description level } } } }",
"variables": {
"where": {
"timeRange": {
"absolute": {
"from": "2026-04-14 15:00:00",
"to": "2026-04-14 16:00:00"
}
},
"groupByTime": "MINUTE"
}
}
}'