Skip to main content
POST
Load Connector Data
tql_path runs saved Ontology .tql files that the caller’s roles can already see — it does not compile caller-authored TQL. Provide exactly one of query or tql_path; sending both or neither returns 400 invalid_request.

Authorizations

Authorization
string
header
required

API key or JWT token

Path Parameters

id
string
required

Sandbox ID

Body

application/json
connector_id
integer<int32>
required

Connector to query

query
string

Inline SQL query to execute. Mutually exclusive with tql_path — provide exactly one of the two (400 invalid_request otherwise).

tql_path
string

Ontology path of a saved .tql file to run (must end in .tql). Only files already visible to the member's roles can be run — a path that is not visible returns 404 not_found, indistinguishable from a path that does not exist. Mutually exclusive with query — provide exactly one of the two (400 invalid_request otherwise).

params
object

Parameter values passed to the saved .tql file when it is rendered. Only used with tql_path. If rendering fails, the request returns 400 with the renderer's message included.

max_rows
integer<int64>

Maximum number of rows to load. Only applies to the tql_path branch; clamped to the range 1–2,000,000 (default 2,000,000).

dataframe_name
string

Name for the resulting dataframe. Defaults to connector_{id} for query, or to the .tql filename stem (e.g. revenue for reports/revenue.tql) for tql_path.

Response

Query result loaded into dataframe

preview
string

Text summary of the loaded data. Format varies by size: for smaller results, a dataframe preview string from the sandbox; for larger results (2048+ rows), a markdown table of the first 100 rows.

dataframe_name
string
num_rows
integer<int64>
num_cols
integer<int64>