POST /btql Endpoint – Request and Response Schema

Last updated: February 11, 2026

Applicable To

Plans: Any

Deployments: Any

Summary

The POST /btql endpoint is referenced in the Braintrust documentation (e.g., for complex queries), but its request payload and response schema are not currently included in the OpenAPI spec.

Required fields:

  • query: string | ParsedQuery - The BTQL query to execute (either as a string or pre-parsed query object)

Optional fields:

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

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

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

  • disable_limit: boolean - Disable default limit

  • force_push_limit: boolean - Force limit to be pushed down to subquery

  • version: string - Version to query

  • audit_log: boolean - Query audit log data

  • use_match_search_index: boolean - Use match search index

  • expected_cost: number - Rough estimate of query cost (scale 1-10)

  • overflow_results: boolean - Overflow large results to object storage

  • inference_depth: number - Schema inference depth for objects

  • relaxed_search_mode: boolean - Disable strict liveness/de-duplication guarantees

  • 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)

  • include_plan: boolean - Include query plan in response

  • custom_column_scope: object - Scope for custom columns

  • query_source: string - Query source identifier for debugging

  • client_version: string - Client commit SHA for debugging

  • scope_to_root_span_id: string - Scope query to specific root_span_id

Response Schema:

{
  rows: Record<string, unknown>[];           // Query result rows
  resultSchema: ResponseSchema;              // Schema describing the result structure
  duckdbSchema?: Record<string, unknown>;    // DuckDB schema (if applicable)
  cursor?: string;                           // Pagination cursor (base64 encoded)
  objectsByType?: Map<string, Record<string, ObjectCacheEntry>>;  // 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
}

Internal links: