Skip to main content
POST
Python SDK

Access

An MCP token or a Parable token can call this operation. See Authentication for the kinds of token. Your roles must grant tenant.data.query.providers.

Errors

  • HTTP 400: A parameter is not a JSON scalar. Send each parameter as a string, finite number, boolean or null.
  • HTTP 403: The caller may not query data in this Workspace. Ask a Workspace Administrator for the Provider Pools Reader role. A different query does not help.
  • HTTP 429: Too many queries were running, so the statement did not start (QL-IN-008), or the caller sent more than 120 of these requests in a minute. Nothing ran. Wait a moment, or for the seconds in the Retry-After header when it is set, then send the same request again.
  • HTTP 503: The statement stopped for lack of memory (QL-IN-009), or a service it needs did not answer, such as the model service behind semantic ranking or a SQL AI function (QL-IN-010). The code says which. Try again shortly. For QL-IN-009, read fewer columns or rows, or aggregate.
  • HTTP 504: The statement ran past its time budget (a QL-TO code) or did not finish in 30 seconds. Narrow the scope or the statement, then send it again.

Authorizations

Authorization
string
header
required

A personal access token, which starts with pat_. A Parable token can call each operation that the roles of its owner allow. An MCP token can call only the read operations that are open to agents. A SQL token does not work on this API.

Headers

X-Tenant
string

Workspace slug. Overrides subdomain-based workspace resolution when provided.

Example:

"acme"

X-Request-ID
string<uuid>

Optional request correlation ID echoed back in the response.

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

One SQL statement to run against the Provider Pools, or to plan without running.

sql
string
required

Single read-only SQL statement. Text.Sql rejects empty; maxLength is 100000 bytes.

Required string length: 1 - 100000
Pattern: ^[\s\S]*$
parameters
any[] | null

Positional values for $1, $2, ... placeholders, sent through Flight SQL prepared-statement binding. Values are never interpolated into SQL. Each value is a JSON scalar (string, finite number, boolean, or null). Identifiers and the arguments of search_available_data cannot be bound.

Any valid JSON value: object, array, primitive, or null

Response

Successful response

data
object
required

What planning a statement produced. Exactly one of the two holds: planned is true and columns are the columns it would return, or planned is false and refusal says why.

meta
object
required