Skip to main content
Applies to:


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.

​
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
}