BTQL POST endpoint payload and response schema

Last updated: February 13, 2026

Summary

Goal: Execute BTQL queries via the POST /btql endpoint with proper request payload and response handling.

Features: Query execution, pagination cursors, multiple output formats (JSON/JSONL/Parquet), schema inference, real-time data support, and query planning.

Applicable To

Plans: Any

Deployments: Any

Request Schema

Required fields

  • query (string | ParsedQuery) - BTQL query to execute

Format and output options

  • fmt ("json" | "jsonl" | "parquet") - Output format (default: "json")

  • api_version (number) - API version (default: 1)

  • inference_depth (number) - Schema inference depth for objects

Query control parameters

  • disable_limit (boolean) - Disable default limit

  • force_push_limit (boolean) - Force limit pushed to subquery

  • expected_cost (number) - Query cost estimate (scale 1-10)

  • overflow_results (boolean) - Overflow large results to object storage

  • relaxed_search_mode (boolean) - Disable strict liveness/de-duplication

Data scoping options

  • version (string) - Version to query

  • audit_log (boolean) - Query audit log data

  • scope_to_root_span_id (string) - Scope to specific root_span_id

  • custom_column_scope (object) - Scope for custom columns

Brainstore parameters

  • use_brainstore (boolean) - Use Brainstore backend

  • brainstore_realtime (boolean) - Use real-time data

  • brainstore_skip_backfill_check (boolean) - Skip backfill check

  • brainstore_ephemeral_wal (boolean) - Use ephemeral WAL for realtime queries

  • realtime_timeout_ms (number) - Timeout for real-time data reads

  • query_timeout_seconds (number) - Query timeout (Brainstore only)

Search and indexing

  • use_match_search_index (boolean) - Use match search index

  • tz_offset (number) - Timezone offset (follows Date.prototype.getTimezoneOffset() convention)

Debugging options

  • include_plan (boolean) - Include query plan in response

  • query_source (string) - Query source identifier for debugging

  • client_version (string) - Client commit SHA for debugging

Response Schema

{
  rows: Record[];                            // Query result rows
  resultSchema: ResponseSchema;              // Schema describing result structure
  duckdbSchema?: Record;                     // DuckDB schema (if applicable)
  cursor?: string;                           // Pagination cursor (base64 encoded)
  objectsByType?: Map>;                      // ACL info
  plan?: string;                             // Query plan (if include_plan=true)
  realtime_state?: RealtimeState;            // Realtime data state
  freshness_state?: FreshnessState;          // Data freshness info
  brainstoreDurationMs?: number;             // Brainstore query duration
}