Skip to main content
POST
/
v2
/
sandcastles
/
{id}
/
query
Load Connector Data
curl --request POST \
  --url https://app.textql.com/v2/sandcastles/{id}/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "connector_id": 123,
  "query": "<string>",
  "tql_path": "<string>",
  "params": {},
  "max_rows": 123,
  "dataframe_name": "<string>"
}
'
{
  "preview": "<string>",
  "dataframe_name": "<string>",
  "num_rows": 123,
  "num_cols": 123
}
tql_path runs saved Context Library .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

Context Library 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>