> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# BTQL POST endpoint payload and response schema

export const plans_0 = "Any"

export const deployments_0 = "Any"

export const data_plane_version_0 = undefined

export const use_case_0 = undefined

<Note>
  **Applies to:**

  * Plan - {plans_0}
  * Deployment - {deployments_0}
  * {data_plane_version_0}
  * {use_case_0}
</Note>

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
* `lint_mode` ("default" | "strict") - Control lint warning behavior. `default` returns warnings alongside results; `strict` blocks the query when any warning fires. See [Lint warnings](/reference/sql/best-practices#lint-warnings).

### 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

```javascript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  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
}

```