X-Airbrx-* response headers

The Gateway adds X-Airbrx-* headers to every response. These headers tell you whether the response came from cache, which rule matched, how long the proxy spent on the request, and — when relevant — when the cached entry was created and when it expires. Read them from any HTTP-aware client.

Always present

These headers appear on every response, regardless of cache outcome.

Header Type Example Meaning
X-Airbrx-Log-ID UUID 7f3c5d2a-9b1e-… Unique request identifier. Include this when reporting issues; support uses it to find the specific request.
X-Airbrx-Version Semver 2.1.0 Gateway version handling this request.
X-Airbrx-Tenant String your-slug Tenant identifier. Echoes the gateway address you connected to.
X-Airbrx-Operation String ExecuteStatement Wire-protocol operation: ExecuteStatement, FetchResults, OpenSession, CloseSession, GetOperationStatus.
X-Airbrx-Execution-Time Integer (ms) 12 Time the Gateway spent on this request, not including warehouse execution.
X-Airbrx-Cache-Status String HIT Cache outcome — see cache status values.

Cache status values

Status What happened Latency
HIT Served from cache. No warehouse compute. Typically <50ms
MISS Not in cache. Forwarded to warehouse, result cached. Warehouse latency
BYPASS Caching disabled for this request (rule, SQL hint, or non-cacheable operation). Warehouse latency
STALE Cached entry expired or invalidated. Re-executed on warehouse. Warehouse latency

Cache headers

These headers appear when caching is relevant to the request.

Header Type Present Meaning
X-Airbrx-Cache-Key SHA-256 hash When caching is enabled Deterministic cache key for this query. Derived from the elements declared in the matching rule.
X-Airbrx-Cache-Rule String When a cache rule matched The id of the rule that determined caching behavior.
X-Airbrx-Cache-Version Timestamp When a cache entry exists Identifier for the specific cached result version.
X-Airbrx-Cached-At ISO 8601 UTC On HIT When this result was originally cached.
X-Airbrx-Cache-Expires-At ISO 8601 UTC On HIT with TTL When the cached entry expires. Absent if no expiration.
X-Airbrx-Query-Hash SHA-256 hash When SQL is parsed Hash of the SQL text. Used for query deduplication.

Performance metrics

Header Type Present Meaning
X-Airbrx-Warehouse-Execution-Time Integer (ms) For warehouse executions Time the warehouse spent executing the query. On HIT, retrieved from cached metadata; on MISS, from the live warehouse response.

Session headers

These appear on session-management operations.

Header Type Present Meaning
X-Airbrx-Session-Spoofed Boolean OpenSession true if the Gateway handled the session locally without opening one against the warehouse; false if a real warehouse session was created.
X-Airbrx-Session-Age Integer (sec) OpenSession Age of the session in seconds since creation.

Example response

A cache hit on an ExecuteStatement request:

HTTP/1.1 200 OK Content-Type: application/x-thrift X-Airbrx-Log-ID: 7f3c5d2a-9b1e-4a8f-b3d6-1c4e8a9b2f7d X-Airbrx-Version: 2.1.0 X-Airbrx-Tenant: your-slug X-Airbrx-Operation: ExecuteStatement X-Airbrx-Execution-Time: 12 X-Airbrx-Cache-Status: HIT X-Airbrx-Cache-Key: 28cdcb24cb29... X-Airbrx-Cache-Rule: cache-aggregates-1h X-Airbrx-Cached-At: 2026-05-07T05:01:10Z X-Airbrx-Cache-Expires-At: 2026-05-07T06:01:10Z X-Airbrx-Warehouse-Execution-Time: 1234

See also